@galaxy-io/dls 1.6.1 → 2.0.0

package/README.md

@@ -1,81 +1,78 @@
 # @galaxy-io/dls
 
-Galaxy Design Language System — a React component library with precompiled styles. Zero bundler configuration required.
+The Galaxy Design Language System: the one React component library for Filament, the GX app and every Galaxy React surface. Monochrome, dense, hairline-quiet; precompiled Linaria CSS read through CSS custom properties, so a theme switch never re-renders the app.
 
 ![NPM Version](https://img.shields.io/npm/v/%40galaxy-io%2Fdls)
 
-## Installation
+## Install
 
 ```bash
-npm install @galaxy-io/dls
-# or
 pnpm add @galaxy-io/dls
 ```
 
-**Peer dependencies:** `react` (18 or 19), `react-dom`, `@tanstack/react-query`
+Node ≥ 22, React 18 or 19, ESM. Heavy single-component libraries (charts, tables, the code editor, code highlighting, Markdown, the cron and color inputs, 3D and animated brand marks) are optional peers; [getting-started.md](./docs/getting-started.md#install) lists which subpath needs which.
 
-## Quick Start
+## Quick start
 
 ```tsx
-// 1. Import the stylesheet once at your app root
+// Once, at the app root: component styles, tokens, fonts.
 import "@galaxy-io/dls/styles.css";
+import "@galaxy-io/dls/tokens.css";
+import "@galaxy-io/dls/fonts.css";
 
-// 2. Wrap your app in the theme provider
-import { GalaxyThemeProvider } from "@galaxy-io/dls/theme/GalaxyTheme";
+import { PlusIcon } from "@phosphor-icons/react";
+import Button, { ButtonVariant } from "@galaxy-io/dls/buttons/Button";
+import Flex, { FlexDirection } from "@galaxy-io/dls/layout/Flex";
+import Text, { TextSize, TextWeight } from "@galaxy-io/dls/text/Text";
+import GalaxyProvider from "@galaxy-io/dls/theme/GalaxyProvider";
 
-// 3. Import components by subpath
-import Button, { ButtonVariant, ButtonSize } from "@galaxy-io/dls/buttons/Button";
-import Text, { TextVariant, TextSize } from "@galaxy-io/dls/text/Text";
-
-function App() {
+export function App() {
   return (
-    <GalaxyThemeProvider>
-      <Text variant={TextVariant.PRIMARY} size={TextSize.BODY_MD}>
-        Hello, Galaxy
-      </Text>
-      <Button
-        label="Get Started"
-        variant={ButtonVariant.PRIMARY}
-        size={ButtonSize.MEDIUM}
-        onClick={() => {}}
-      />
-    </GalaxyThemeProvider>
+    <GalaxyProvider>
+      <Flex direction={FlexDirection.COLUMN} gap={16} padding={24}>
+        <Text as="h1" size={TextSize.HEADING_MD} weight={TextWeight.MEDIUM}>
+          Sources
+        </Text>
+        <Flex gap={8}>
+          <Button label="New source" icon={PlusIcon} />
+          <Button label="Import" variant={ButtonVariant.SECONDARY} />
+        </Flex>
+      </Flex>
+    </GalaxyProvider>
   );
 }
 ```
 
-## Theming
+- Import every component from its own subpath; its enums come from the same module. There is no barrel.
+- `GalaxyProvider` is the one root: theme (System / Dark / Light), the overlay stack and toasts.
+- Style your own code with Linaria and the token accessor `t` (`@galaxy-io/dls/theme/tokens/t`), set up with `galaxyDls()` from `@galaxy-io/dls/vite`. Lint with `"extends": ["@galaxy-io/dls/biome"]`.
 
-The provider respects system preferences by default:
+## Documentation
 
-```tsx
-import { GalaxyThemeProvider } from "@galaxy-io/dls/theme/GalaxyTheme";
-import { GalaxyTheme } from "@galaxy-io/dls/theme/constants";
+| | |
+|---|---|
+| [Getting started](./docs/getting-started.md) | Install, Vite, stylesheets, provider, SSR |
+| [Theming](./docs/theming.md) | Themes and every token |
+| [Components](./docs/components.md) | Every component, when to use it, examples |
+| [Patterns](./docs/patterns.md) | How Galaxy screens are built |
+| [Accessibility](./docs/accessibility.md) | The floor and the keyboard maps |
+| [Migrating from 1.x](./docs/MIGRATION.md) | The codemod and every change since 1.6.1 |
+| [Contributing](./docs/contributing.md) | Working on this repository ([AGENTS.md](./AGENTS.md) has the rules) |
+| [Storybook](https://storybook.getgalaxy.io) | Every component, prop and state, in both themes |
 
-// System preference (default)
-<GalaxyThemeProvider />
+## Migrating from 1.x
 
-// Force a specific theme
-<GalaxyThemeProvider initialTheme={GalaxyTheme.DARK} />
+```bash
+npx @galaxy-io/dls-codemod src --report dls-migrate.json
 ```
 
-Access theme state in components:
-
-```tsx
-import { useGalaxyTheme } from "@galaxy-io/dls/theme/GalaxyTheme";
-
-function ThemeSwitcher() {
-  const { activeTheme, selectedTheme, setTheme } = useGalaxyTheme();
-}
-```
+The codemod rewrites everything mechanical and marks the rest with `@dls-migrate <id>` comments; [docs/MIGRATION.md](./docs/MIGRATION.md) explains every id.
 
-## Components
+## Claude skill
 
-Import from subpaths — there is no barrel export:
+[`skills/galaxy-ui`](./skills/galaxy-ui/SKILL.md) teaches Claude to design and build Galaxy UIs with this package: the workflow, the brand rules, the component decision tables, tokens, patterns and complete screen recipes. Its examples are type-checked against this repository (`pnpm skill:check`).
 
-```tsx
-import Button from "@galaxy-io/dls/buttons/Button";
-import Text from "@galaxy-io/dls/text/Text";
-```
+- **Claude Code:** copy the folder into your skills directory: `cp -R skills/galaxy-ui ~/.claude/skills/` (or a project's `.claude/skills/`).
+- **Claude apps:** run `pnpm skill:pack` and upload `dist-skill/galaxy-ui.zip` as a skill (Settings → Capabilities → Skills).
 
-To explore all available components, visit [Storybook](https://storybook.getgalaxy.io).
+Details: [skills/galaxy-ui/README.md](./skills/galaxy-ui/README.md).

package/biome/index.json

@@ -0,0 +1,74 @@
+{
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space",
+    "indentWidth": 2,
+    "lineWidth": 100
+  },
+  "javascript": {
+    "formatter": {
+      "quoteStyle": "double",
+      "trailingCommas": "all",
+      "semicolons": "always"
+    }
+  },
+  "json": {
+    "formatter": {
+      "trailingCommas": "none"
+    }
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "preset": "recommended",
+      "correctness": {
+        "noRestrictedElements": {
+          "level": "warn",
+          "options": {
+            "elements": {
+              "p": "DLS: render text through `Text as=\"p\"`.",
+              "h1": "DLS: render headings through `Text as=\"h1\"`.",
+              "h2": "DLS: render headings through `Text as=\"h2\"`.",
+              "h3": "DLS: render headings through `Text as=\"h3\"`.",
+              "h4": "DLS: render headings through `Text as=\"h4\"`.",
+              "h5": "DLS: render headings through `Text as=\"h5\"`.",
+              "h6": "DLS: render headings through `Text as=\"h6\"`.",
+              "span": "DLS: render inline text through `Span`.",
+              "label": "DLS: render labels through `Text as=\"label\"` (or `Field`)."
+            }
+          }
+        }
+      },
+      "performance": {
+        "noBarrelFile": "warn",
+        "noReExportAll": "warn"
+      }
+    }
+  },
+  "plugins": [
+    {
+      "path": "./node_modules/@galaxy-io/dls/biome/plugins/warn/no-hex-literal.grit",
+      "includes": ["**", "!**/*.test.ts", "!**/*.test.tsx"]
+    },
+    {
+      "path": "./node_modules/@galaxy-io/dls/biome/plugins/warn/no-margin.grit",
+      "includes": ["**"]
+    },
+    {
+      "path": "./node_modules/@galaxy-io/dls/biome/plugins/warn/no-inline-style.grit",
+      "includes": ["**", "!**/*.stories.tsx"]
+    }
+  ],
+  "overrides": [
+    {
+      "includes": ["**/*.stories.tsx", "**/*.mdx"],
+      "linter": {
+        "rules": {
+          "correctness": {
+            "noRestrictedElements": "off"
+          }
+        }
+      }
+    }
+  ]
+}

package/biome/plugins/no-hex-literal.grit

@@ -0,0 +1,20 @@
+// DLS: no hex color literal outside src/theme/tokens/ (Constitution III.5).
+// Scoped in biome.json (`plugins[].includes`); colors come from `t.color.*`.
+language js
+
+or {
+  JsStringLiteralExpression() as $literal where {
+    $literal <: r"(?s).*#(?:[0-9a-fA-F]{8}|[0-9a-fA-F]{6}|[0-9a-fA-F]{3,4})\b.*"
+  },
+  JsTemplateChunkElement() as $literal where {
+    $literal <: r"(?s).*#(?:[0-9a-fA-F]{8}|[0-9a-fA-F]{6}|[0-9a-fA-F]{3,4})\b.*"
+  },
+  JsxString() as $literal where {
+    $literal <: r"(?s).*#(?:[0-9a-fA-F]{8}|[0-9a-fA-F]{6}|[0-9a-fA-F]{3,4})\b.*"
+  },
+  JsxText() as $literal where {
+    $literal <: r"(?s).*#(?:[0-9a-fA-F]{8}|[0-9a-fA-F]{6}|[0-9a-fA-F]{3,4})\b.*"
+  }
+} where {
+  register_diagnostic(span=$literal, message="DLS: no hex color literal outside src/theme/tokens/. Use a `t.color.*` token.", severity="error")
+}

package/biome/plugins/no-inline-style.grit

@@ -0,0 +1,13 @@
+// DLS: no inline `style={{ … }}` except to set CSS custom properties (Constitution IV.1).
+// `style={{ "--gx-x": value, ["--gx-y"]: value, ...style }}` is fine; `style={{ color: … }}`,
+// `style={{ color }}` (shorthand) and `style={{ [key]: … }}` (non-`--` computed key) are not.
+language js
+
+JsxAttribute(name=$name, initializer=$value) where {
+  $name <: "style",
+  $value <: contains or {
+    JsPropertyObjectMember(name=$key) as $member where { $key <: not r"(?s)(?:\[\s*)?[\"'`]--.*" },
+    JsShorthandPropertyObjectMember() as $member
+  },
+  register_diagnostic(span=$member, message="DLS: inline style may only set CSS custom properties (`--gx-*`). Style with Linaria.", severity="error")
+}

package/biome/plugins/no-margin.grit

@@ -0,0 +1,9 @@
+// DLS: margins are forbidden (Constitution II.5). Spacing is `gap` and `padding` only.
+// Matches any `margin` / `margin-*` declaration with a non-zero value inside a template
+// (Linaria `css` / `styled`). `margin: 0` (a reset) is allowed.
+language js
+
+JsTemplateChunkElement() as $chunk where {
+  $chunk <: r"(?s).*(?:^|[^-a-zA-Z])margin(?:-[a-z]+)*\s*:\s*(?:[1-9]|0\.|0\s+[^;\s]|-|[a-zA-Z]|$).*",
+  register_diagnostic(span=$chunk, message="DLS: no margins. Use `gap` / `padding` on Flex, Grid or Box.", severity="error")
+}

package/biome/plugins/warn/no-hex-literal.grit

@@ -0,0 +1,23 @@
+// DLS: no hex color literal (Constitution III.5). Colors come from `t.color.*`.
+// Warn copy of biome/plugins/no-hex-literal.grit for the @galaxy-io/dls/biome preset; the pattern
+// must stay identical (scripts/biome-preset.test.ts). Scoped in biome/index.json. An app's own
+// file of hex values (chart seeds, brand assets) opts out with
+// `// biome-ignore-all lint/plugin: <reason>`.
+language js
+
+or {
+  JsStringLiteralExpression() as $literal where {
+    $literal <: r"(?s).*#(?:[0-9a-fA-F]{8}|[0-9a-fA-F]{6}|[0-9a-fA-F]{3,4})\b.*"
+  },
+  JsTemplateChunkElement() as $literal where {
+    $literal <: r"(?s).*#(?:[0-9a-fA-F]{8}|[0-9a-fA-F]{6}|[0-9a-fA-F]{3,4})\b.*"
+  },
+  JsxString() as $literal where {
+    $literal <: r"(?s).*#(?:[0-9a-fA-F]{8}|[0-9a-fA-F]{6}|[0-9a-fA-F]{3,4})\b.*"
+  },
+  JsxText() as $literal where {
+    $literal <: r"(?s).*#(?:[0-9a-fA-F]{8}|[0-9a-fA-F]{6}|[0-9a-fA-F]{3,4})\b.*"
+  }
+} where {
+  register_diagnostic(span=$literal, message="DLS: no hex color literal. Use a `t.color.*` token.", severity="warn")
+}

package/biome/plugins/warn/no-inline-style.grit

@@ -0,0 +1,13 @@
+// DLS: no inline `style={{ … }}` except to set CSS custom properties (Constitution IV.1).
+// Warn copy of biome/plugins/no-inline-style.grit for the @galaxy-io/dls/biome preset; the pattern
+// must stay identical (scripts/biome-preset.test.ts). Scoped in biome/index.json.
+language js
+
+JsxAttribute(name=$name, initializer=$value) where {
+  $name <: "style",
+  $value <: contains or {
+    JsPropertyObjectMember(name=$key) as $member where { $key <: not r"(?s)(?:\[\s*)?[\"'`]--.*" },
+    JsShorthandPropertyObjectMember() as $member
+  },
+  register_diagnostic(span=$member, message="DLS: inline style may only set CSS custom properties (`--gx-*`). Style with Linaria.", severity="warn")
+}

package/biome/plugins/warn/no-margin.grit

@@ -0,0 +1,9 @@
+// DLS: margins are forbidden (Constitution II.5). Spacing is `gap` and `padding` only.
+// Warn copy of biome/plugins/no-margin.grit for the @galaxy-io/dls/biome preset; the pattern must
+// stay identical (scripts/biome-preset.test.ts). `margin: 0` (a reset) is allowed.
+language js
+
+JsTemplateChunkElement() as $chunk where {
+  $chunk <: r"(?s).*(?:^|[^-a-zA-Z])margin(?:-[a-z]+)*\s*:\s*(?:[1-9]|0\.|0\s+[^;\s]|-|[a-zA-Z]|$).*",
+  register_diagnostic(span=$chunk, message="DLS: no margins. Use `gap` / `padding` on Flex, Grid or Box.", severity="warn")
+}

package/dist/a11y/FocusScope.d.ts

@@ -0,0 +1,44 @@
+import { type AriaAttributes, type CSSProperties, type ReactNode } from "react";
+/** Where focus goes on mount. */
+export declare enum FocusScopeAutoFocus {
+    /** The first tabbable element, or the scope itself when there is none. */
+    FIRST = "FIRST",
+    /** Nowhere: focus stays where it is. */
+    NONE = "NONE"
+}
+export interface FocusScopeProps extends AriaAttributes {
+    /** The region focus is kept in. */
+    children?: ReactNode;
+    /**
+     * Keep focus inside: Tab and Shift+Tab wrap at the edges and focus that leaves is pulled back.
+     * Defaults to `true` on purpose (a behavior-primitive exception to Article V's `false` default):
+     * a focus trap that does not trap by default would be a footgun.
+     * @default true
+     */
+    isTrapped?: boolean;
+    /**
+     * On unmount, return focus to the element that had it before the scope mounted. Defaults to
+     * `true` on purpose (a behavior-primitive exception to Article V's `false` default).
+     * @default true
+     */
+    shouldRestoreFocus?: boolean;
+    /**
+     * On mount, focus the first tabbable element (or the scope itself when there is none) unless
+     * focus is already inside; `NONE` leaves focus where it is.
+     * @default FocusScopeAutoFocus.FIRST
+     */
+    autoFocus?: FocusScopeAutoFocus;
+    /** Escape was pressed inside the scope. The innermost scope with a handler gets it. */
+    onEscape?: () => void;
+    /** DOM id of the scope element. */
+    id?: string;
+    /** Any `data-*` attribute, forwarded to the scope element. */
+    [dataAttribute: `data-${string}`]: string | number | boolean | undefined;
+    /** Extra class on the scope element. */
+    className?: string;
+    /** Inline style on the scope element; only for setting CSS custom properties. */
+    style?: CSSProperties;
+}
+/** Keeps focus inside its children while mounted. */
+declare const FocusScope: import("react").ForwardRefExoticComponent<FocusScopeProps & import("react").RefAttributes<HTMLDivElement>>;
+export default FocusScope;

package/dist/a11y/FocusScope.js

@@ -0,0 +1,229 @@
+import { useIsomorphicLayoutEffect } from "../hooks/useIsomorphicLayoutEffect.js";
+/* empty css                     */
+import { styled } from "@linaria/react";
+import { createContext, forwardRef, useCallback, useContext, useRef, useState } from "react";
+import { jsx } from "react/jsx-runtime";
+//#region src/a11y/FocusScope.tsx
+/**
+* Keeps keyboard focus inside a region while it is mounted: moves focus in on mount, wraps Tab and
+* Shift+Tab at the edges, pulls focus back when it escapes, and returns it to where it was on
+* unmount. `Modal`, `Drawer`, `Menu` and `CommandPalette` are built on it.
+*
+* - **Nested scopes, innermost wins.** Only the innermost trapped scope enforces its trap; an outer
+*   scope pauses while a scope rendered inside it (in the React tree) is trapped, and resumes when
+*   that scope unmounts or stops trapping. Escape goes to the innermost scope with an `onEscape`.
+* - **Portals.** "Inside" follows the React tree, not the DOM: focus in a portal rendered from
+*   within the scope (a Menu opened from a Modal) counts as inside, because React focus and key
+*   events bubble through portals to the scope.
+*
+* The scope renders one unstyled `div` (plus `FOCUS_RING`, for when it holds focus itself because
+* it has nothing tabbable). SSR-safe: `document` is read only in effects and handlers.
+*/
+/** Where focus goes on mount. */
+var FocusScopeAutoFocus = /* @__PURE__ */ function(FocusScopeAutoFocus) {
+	/** The first tabbable element, or the scope itself when there is none. */
+	FocusScopeAutoFocus["FIRST"] = "FIRST";
+	/** Nowhere: focus stays where it is. */
+	FocusScopeAutoFocus["NONE"] = "NONE";
+	return FocusScopeAutoFocus;
+}({});
+/**
+* Trapped scopes in the order they started trapping. Module state holds no DOM, so the module
+* stays SSR-safe; it is only read and written from effects and event handlers.
+*/
+var TRAPPED_SCOPES = [];
+/** The enclosing scope, for nesting. Context crosses portals, like the events do. */
+var FocusScopeContext = createContext(null);
+/** Candidates for sequential focus; `tabbableElements` filters them further. */
+var TABBABLE_SELECTOR = [
+	"a[href]",
+	"area[href]",
+	"button:not(:disabled)",
+	"input:not(:disabled):not([type=\"hidden\"])",
+	"select:not(:disabled)",
+	"textarea:not(:disabled)",
+	"iframe",
+	"audio[controls]",
+	"video[controls]",
+	"summary",
+	"[contenteditable]:not([contenteditable=\"false\"])",
+	"[tabindex]"
+].join(",");
+var isAncestor = (ancestor, node) => {
+	for (let parent = node.parent; parent !== null; parent = parent.parent) if (parent === ancestor) return true;
+	return false;
+};
+/**
+* The scope whose trap is in force: the most recent trapped scope with no trapped scope nested
+* inside it.
+*/
+var activeScope = () => {
+	for (let index = TRAPPED_SCOPES.length - 1; index >= 0; index -= 1) {
+		const scope = TRAPPED_SCOPES[index];
+		if (scope && !TRAPPED_SCOPES.some((other) => other !== scope && isAncestor(scope, other))) return scope;
+	}
+	return null;
+};
+var isRendered = (element) => element.getClientRects().length > 0 && getComputedStyle(element).visibility !== "hidden";
+/** A radio is tabbable when it is the checked one of its group, or the group has none checked. */
+var isTabbableRadio = (element, root) => {
+	if (!(element instanceof HTMLInputElement) || element.type !== "radio" || element.name === "") return true;
+	const group = Array.from(root.querySelectorAll(`input[type="radio"][name="${CSS.escape(element.name)}"]`)).filter((radio) => radio.form === element.form);
+	const checked = group.find((radio) => radio.checked);
+	return checked ? checked === element : group[0] === element;
+};
+/** The elements under `root` that Tab visits, in Tab order (positive `tabindex` first). */
+var tabbableElements = (root) => {
+	const candidates = Array.from(root.querySelectorAll(TABBABLE_SELECTOR)).filter((element) => element.tabIndex >= 0 && element.closest("[inert]") === null && isRendered(element) && isTabbableRadio(element, root));
+	return [...candidates.filter((element) => element.tabIndex > 0).sort((a, b) => a.tabIndex - b.tabIndex), ...candidates.filter((element) => element.tabIndex === 0)];
+};
+/** Focus the first (or last) tabbable element under `root`, or `root` itself when there is none. */
+var focusEdge = (root, edge) => {
+	const tabbables = tabbableElements(root);
+	((edge === "first" ? tabbables[0] : tabbables.at(-1)) ?? root).focus();
+};
+var Root = /*#__PURE__*/ styled("div")({
+	name: "Root",
+	class: "gx-FocusScope-ry2i33n",
+	propsAsIs: false
+});
+/** Keeps focus inside its children while mounted. */
+var FocusScope = forwardRef(function FocusScope({ children, isTrapped = true, shouldRestoreFocus = true, autoFocus = "FIRST", onEscape, id, className, style, ...rest }, ref) {
+	const parent = useContext(FocusScopeContext);
+	const [scope] = useState(() => ({ parent }));
+	/** Focus before the scope mounted, read on the first render (before any child `autoFocus`). */
+	const [focusBeforeMount] = useState(() => typeof document === "undefined" ? null : document.activeElement);
+	const rootRef = useRef(null);
+	/** The last element focused inside the scope, including in portals. */
+	const lastFocusedRef = useRef(null);
+	/** The last element focused in the scope's own DOM (not a portal): a portal's anchor. */
+	const lastFocusedInRootRef = useRef(null);
+	/** The last native focus or key event React delivered to the scope (DOM or portal descendant). */
+	const insideEventRef = useRef(null);
+	const shouldRestoreFocusRef = useRef(shouldRestoreFocus);
+	shouldRestoreFocusRef.current = shouldRestoreFocus;
+	const autoFocusRef = useRef(autoFocus);
+	autoFocusRef.current = autoFocus;
+	const setRootRef = useCallback((node) => {
+		rootRef.current = node;
+		if (typeof ref === "function") ref(node);
+		else if (ref) ref.current = node;
+	}, [ref]);
+	useIsomorphicLayoutEffect(() => {
+		const root = rootRef.current;
+		if (!isTrapped || root === null) return;
+		TRAPPED_SCOPES.push(scope);
+		const isActive = () => activeScope() === scope;
+		const isInside = (event) => event.target instanceof Node && root.contains(event.target) || insideEventRef.current === event;
+		/** Set by a Tab pressed in a portal of this scope, for the focus move that follows it. */
+		let portalTab = null;
+		let portalTabTimer;
+		const onKeyDown = (event) => {
+			if (event.key !== "Tab" || event.defaultPrevented || !isActive()) return;
+			if (event.altKey || event.ctrlKey || event.metaKey) return;
+			const target = event.target;
+			if (!(target instanceof Element) || !root.contains(target)) {
+				if (isInside(event)) {
+					portalTab = event.shiftKey ? "backward" : "forward";
+					clearTimeout(portalTabTimer);
+					portalTabTimer = setTimeout(() => {
+						portalTab = null;
+					});
+					return;
+				}
+				event.preventDefault();
+				focusEdge(root, event.shiftKey ? "last" : "first");
+				return;
+			}
+			const tabbables = tabbableElements(root);
+			const first = tabbables[0];
+			const last = tabbables.at(-1);
+			if (first === void 0 || last === void 0) {
+				event.preventDefault();
+				root.focus();
+				return;
+			}
+			const index = tabbables.indexOf(target);
+			if (index === -1) {
+				event.preventDefault();
+				(event.shiftKey ? tabbables.findLast((element) => (target.compareDocumentPosition(element) & Node.DOCUMENT_POSITION_PRECEDING) !== 0) ?? last : tabbables.find((element) => (target.compareDocumentPosition(element) & Node.DOCUMENT_POSITION_FOLLOWING) !== 0) ?? first).focus();
+			} else if (event.shiftKey && index === 0) {
+				event.preventDefault();
+				last.focus();
+			} else if (!event.shiftKey && index === tabbables.length - 1) {
+				event.preventDefault();
+				first.focus();
+			}
+		};
+		const onFocusIn = (event) => {
+			const direction = portalTab;
+			portalTab = null;
+			if (!isActive() || isInside(event)) return;
+			const anchor = lastFocusedInRootRef.current;
+			const hasAnchor = (anchor instanceof HTMLElement || anchor instanceof SVGElement) && root.contains(anchor);
+			if (direction !== null && hasAnchor) {
+				const next = direction === "forward" ? tabbableElements(root).find((element) => (anchor.compareDocumentPosition(element) & Node.DOCUMENT_POSITION_FOLLOWING) !== 0) : anchor;
+				if (next) next.focus();
+				else focusEdge(root, "first");
+				return;
+			}
+			const previous = lastFocusedRef.current;
+			if ((previous instanceof HTMLElement || previous instanceof SVGElement) && previous.isConnected) {
+				previous.focus();
+				return;
+			}
+			focusEdge(root, "first");
+		};
+		document.addEventListener("keydown", onKeyDown);
+		document.addEventListener("focusin", onFocusIn);
+		return () => {
+			document.removeEventListener("keydown", onKeyDown);
+			document.removeEventListener("focusin", onFocusIn);
+			clearTimeout(portalTabTimer);
+			const index = TRAPPED_SCOPES.lastIndexOf(scope);
+			if (index !== -1) TRAPPED_SCOPES.splice(index, 1);
+		};
+	}, [isTrapped, scope]);
+	useIsomorphicLayoutEffect(() => {
+		const root = rootRef.current;
+		if (root === null) return;
+		if (autoFocusRef.current === "FIRST" && !root.contains(document.activeElement)) focusEdge(root, "first");
+		return () => {
+			if (!shouldRestoreFocusRef.current) return;
+			const active = document.activeElement;
+			if ((active === null || active === document.body || root.contains(active) || active === lastFocusedRef.current) && (focusBeforeMount instanceof HTMLElement || focusBeforeMount instanceof SVGElement) && focusBeforeMount.isConnected) focusBeforeMount.focus();
+		};
+	}, [focusBeforeMount]);
+	const onFocusCapture = (event) => {
+		insideEventRef.current = event.nativeEvent;
+		lastFocusedRef.current = event.target;
+		if (event.currentTarget.contains(event.target)) lastFocusedInRootRef.current = event.target;
+	};
+	const onKeyDownCapture = (event) => {
+		insideEventRef.current = event.nativeEvent;
+	};
+	const onKeyDown = (event) => {
+		if (event.key !== "Escape" || onEscape === void 0) return;
+		if (event.defaultPrevented || event.nativeEvent.isComposing) return;
+		event.stopPropagation();
+		onEscape();
+	};
+	return /* @__PURE__ */ jsx(FocusScopeContext.Provider, {
+		value: scope,
+		children: /* @__PURE__ */ jsx(Root, {
+			...rest,
+			ref: setRootRef,
+			id,
+			tabIndex: -1,
+			onFocusCapture,
+			onKeyDownCapture,
+			onKeyDown,
+			className,
+			style,
+			children
+		})
+	});
+});
+FocusScope.displayName = "FocusScope";
+//#endregion
+export { FocusScopeAutoFocus, FocusScope as default };

package/dist/a11y/VisuallyHidden.d.ts

@@ -0,0 +1,21 @@
+import { type AriaAttributes, type CSSProperties, type ElementType, type ReactNode } from "react";
+export interface VisuallyHiddenProps extends AriaAttributes {
+    /** What screen readers announce. */
+    children?: ReactNode;
+    /**
+     * Element or component to render (`"div"` for block content, `"label"` for a hidden label).
+     * @default "span"
+     */
+    as?: ElementType;
+    /** DOM id, e.g. the target of an `aria-describedby`. */
+    id?: string;
+    /** Any `data-*` attribute, forwarded to the root element. */
+    [dataAttribute: `data-${string}`]: string | number | boolean | undefined;
+    /** Extra class on the root element. */
+    className?: string;
+    /** Inline style on the root element; only for setting CSS custom properties. */
+    style?: CSSProperties;
+}
+/** Renders its children for assistive technology only. */
+declare const VisuallyHidden: import("react").ForwardRefExoticComponent<VisuallyHiddenProps & import("react").RefAttributes<HTMLElement>>;
+export default VisuallyHidden;

package/dist/a11y/VisuallyHidden.js

@@ -0,0 +1,30 @@
+/* empty css                         */
+import { styled } from "@linaria/react";
+import { forwardRef } from "react";
+import { jsx } from "react/jsx-runtime";
+//#region src/a11y/VisuallyHidden.tsx
+/**
+* Content for screen readers only: removed from the visual layout with the `VISUALLY_HIDDEN`
+* mixin, still in the accessibility tree. Use it for the accessible name of an icon-only control,
+* a live-region announcement, or a heading a sighted user does not need.
+*/
+var Root = /*#__PURE__*/ styled("span")({
+	name: "Root",
+	class: "gx-VisuallyHidden-r1n9rkuz",
+	propsAsIs: false
+});
+/** Renders its children for assistive technology only. */
+var VisuallyHidden = forwardRef(function VisuallyHidden({ children, as = "span", id, className, style, ...rest }, ref) {
+	return /* @__PURE__ */ jsx(Root, {
+		...rest,
+		as,
+		ref,
+		id,
+		className,
+		style,
+		children
+	});
+});
+VisuallyHidden.displayName = "VisuallyHidden";
+//#endregion
+export { VisuallyHidden as default };