@galaxy-io/dls 1.6.1 → 2.0.1

package/dist/theme/tokens/t.js

@@ -0,0 +1,25 @@
+import { DARK_THEME } from "./dark.js";
+import { SCALES, tokenName } from "./generate.js";
+//#region src/theme/tokens/t.ts
+/**
+* `t` — the typed token accessor. Every leaf is the `var(--gx-…)` string for that token, so
+* styles follow the active theme through CSS alone:
+*
+* ```ts
+* const Panel = styled.div`
+*   background: ${t.color.background.primary};   // var(--gx-color-background-primary)
+*   padding: ${t.space[12]};                       // var(--gx-space-12)
+* `;
+* ```
+*
+* Built by walking the token source with `tokenName`, the same function that names the CSS
+* variables, and typed `TokenAccessor<Theme & Scales>`, so `t` cannot drift from `Theme`.
+*/
+var toAccessor = (node, path) => Object.fromEntries(Object.entries(node).map(([key, value]) => [key, typeof value === "object" && value !== null ? toAccessor(value, [...path, key]) : `var(${tokenName([...path, key])})`]));
+/** Typed `var(--gx-…)` accessor for every token. Style with `t.*` only. */
+var t = toAccessor({
+	...DARK_THEME,
+	...SCALES
+}, []);
+//#endregion
+export { t };

package/dist/theme/tokens/types.d.ts

@@ -0,0 +1,189 @@
+/**
+ * The shape of the token layer (AGENTS.md; docs/theming.md). `Theme` is
+ * what changes per theme; `Scales` is theme-independent. `t` is typed
+ * `TokenAccessor<Theme & Scales>`, so the accessor and the theme cannot diverge.
+ */
+import type { Space } from "../enums.js";
+/** A `#rrggbb` (or `#rgb`) color. */
+export type Hex = `#${string}`;
+/**
+ * The 17 chromatic families of the mode-stable palette (Tailwind v4 hues). There is no gray family:
+ * neutrals are the theme's `primary / secondary / tertiary` roles.
+ */
+export type PaletteColor = "red" | "orange" | "amber" | "yellow" | "lime" | "green" | "emerald" | "teal" | "cyan" | "sky" | "blue" | "indigo" | "violet" | "purple" | "fuchsia" | "pink" | "rose";
+/**
+ * The five steps of every palette family, lightest (`100`) to darkest (`900`): Tailwind v4's 50,
+ * 200, 500, 800 and 950.
+ */
+export type PaletteStep = 100 | 300 | 500 | 700 | 900;
+/**
+ * The status roles every color property carries. Their values are their own (not copies of a
+ * palette family): a green, a warm amber and a red that never read alike.
+ */
+export type StatusColor = "success" | "warning" | "error";
+/** One value per meaning role and per palette family. */
+type RoleColors = Record<StatusColor | PaletteColor, string>;
+/** A strong fill: its background, the text and icons drawn on it, and its two states. */
+export type SolidColor = {
+    /** The fill. */
+    background: string;
+    /** Text and icons drawn on the fill. */
+    text: string;
+    /** The fill on hover. */
+    hovered: string;
+    /** The fill while pressed. */
+    pressed: string;
+};
+/** Type-scale steps (Constitution III-A.1). */
+export type TypeStep = "caption" | "body_sm" | "body_md" | "body_lg" | "heading_sm" | "heading_md" | "heading_lg" | "display_sm" | "display_lg";
+/** Serif (Cardo) is editorial only: it has no `caption`, `body_sm` or `body_md` step. */
+type SerifStep = Exclude<TypeStep, "caption" | "body_sm" | "body_md">;
+/** One family's metrics. Generic over its steps so a missing step is a type error. */
+export type FontScale<S extends TypeStep = TypeStep> = {
+    /** CSS `font-family` stack. */
+    family: string;
+    /** The only two weights (Constitution II.4). */
+    weight: {
+        regular: number;
+        medium: number;
+    };
+    /** `font-size` per step. */
+    size: Record<S, string>;
+    /** UI `line-height` per step, on the 4px grid. Prose uses `1.5` instead. */
+    height: Record<S, string>;
+    /** `letter-spacing` per step. */
+    spacing: Record<S, string>;
+};
+/**
+ * Everything that changes per theme. Resolved hex values; `t` mirrors it as `var(--gx-…)`.
+ * Property-first: `t.color.<property>.<role>`, one value per role, no `subtle/default/strong`.
+ */
+export type Theme = {
+    color: {
+        /** Fills: surfaces, interaction states, and the soft tint of every role. */
+        background: RoleColors & {
+            /** The canvas. */
+            base: string;
+            /** Panels. */
+            primary: string;
+            /** Raised surfaces. */
+            secondary: string;
+            /** The most elevated surface. */
+            tertiary: string;
+            /** A neutral row or control under the pointer. */
+            hovered: string;
+            /** A neutral row or control while pressed. */
+            pressed: string;
+            /** The chosen item (menus, trees, tabs, nav, tables): `text.primary` at 12% over `base`. */
+            selected: string;
+            /** Disabled controls. */
+            disabled: string;
+        };
+        /** Text **and** icons. */
+        text: RoleColors & {
+            /** Primary copy. */
+            primary: string;
+            /** Supporting copy. */
+            secondary: string;
+            /** Hints, placeholders, metadata. */
+            tertiary: string;
+            /** Disabled controls. */
+            disabled: string;
+        };
+        /** Hairlines, dividers and control frames. */
+        border: RoleColors & {
+            /** Default hairline; field frames at rest. */
+            primary: string;
+            /** Control borders. */
+            secondary: string;
+            /** Emphasized dividers. */
+            tertiary: string;
+            /** A field frame under the pointer. */
+            hovered: string;
+            /** Focus: field frames and `FOCUS_RING`. */
+            focused: string;
+            /** Disabled controls. */
+            disabled: string;
+        };
+        /**
+         * Fills with the text drawn on them. `primary` is the monochrome fill (`text.primary` with
+         * `background.base` on it): the primary button, checked controls, the brand mark. `neutral` is
+         * the muted fill (`background.secondary` with `text.primary` on it; the `BASE` button), its
+         * hover and press each a clearly visible step in both themes. The rest are strong fills.
+         */
+        solid: Record<"primary" | "neutral" | StatusColor | PaletteColor, SolidColor>;
+        /** Black/white overlays: `bgN` is the canvas color at N% opacity, `fgN` the text color. */
+        opacity: {
+            bg4: string;
+            bg8: string;
+            bg12: string;
+            bg16: string;
+            bg24: string;
+            bg32: string;
+            bg48: string;
+            bg64: string;
+            bg80: string;
+            bg100: string;
+            fg4: string;
+            fg8: string;
+            fg12: string;
+            fg16: string;
+            fg24: string;
+            fg32: string;
+            fg48: string;
+            fg64: string;
+            fg80: string;
+            fg100: string;
+        };
+    };
+    font: {
+        /** UI copy (ABC Diatype). */
+        sans: FontScale;
+        /** Data and code (Berkeley Mono), ~0.92× the sans size at the same line height. */
+        mono: FontScale;
+        /** Editorial copy (Cardo). */
+        serif: FontScale<SerifStep>;
+    };
+};
+/** Theme-independent scales, emitted once on `:root`. */
+export type Scales = {
+    /** Gap and padding (Constitution II.5). */
+    space: Record<Space, string>;
+    /** Corner radii (Constitution II.6). */
+    radius: {
+        sm: string;
+        md: string;
+        lg: string;
+        pill: string;
+    };
+    /** Transition durations (Constitution II.7). */
+    duration: {
+        fast: string;
+        base: string;
+    };
+    /** Stacking order of floating layers. */
+    z: {
+        dropdown: number;
+        drawer: number;
+        modal: number;
+        toast: number;
+        tooltip: number;
+    };
+    /** Control heights: the canonical size rungs (Constitution III-A.4). */
+    size: {
+        control: {
+            xSmall: string;
+            small: string;
+            medium: string;
+            large: string;
+            xLarge: string;
+        };
+    };
+    /** The mode-stable primitive palette: the same hex in every theme. For app-side chart and canvas code that needs a fixed hex; DLS charts draw series with `t.color.text.<family>`. */
+    palette: Record<PaletteColor, Record<PaletteStep, string>>;
+};
+/** Mirrors a token tree with every leaf replaced by its `var(--gx-…)` string. */
+export type TokenAccessor<T> = {
+    [K in keyof T]: T[K] extends string | number ? string : TokenAccessor<T[K]>;
+};
+export {};

package/dist/theme/useGalaxyTheme.d.ts

@@ -0,0 +1,46 @@
+import type { GalaxyTheme, ReducedMotion } from "./enums.js";
+import type { Theme } from "./tokens/types.js";
+/** What `useGalaxyTheme()` returns. */
+export interface GalaxyThemeContextValue {
+    /** Resolved hex object for the active theme. For JS logic, never for styles. */
+    theme: Theme;
+    /** The theme actually rendering. Never SYSTEM. */
+    activeTheme: GalaxyTheme.DARK | GalaxyTheme.LIGHT;
+    /** The stored preference. Can be SYSTEM. Bind pickers to this. */
+    selectedTheme: GalaxyTheme;
+    /** What the OS reports. */
+    systemTheme: GalaxyTheme.DARK | GalaxyTheme.LIGHT;
+    /** Whether the provider's detector can read an OS theme at all. */
+    isSystemThemeSupported: boolean;
+    /** Change the theme preference; persists through the provider's `storage`. */
+    setTheme: (theme: GalaxyTheme) => void;
+    /** The provider's reduced-motion policy. */
+    reducedMotion: ReducedMotion;
+}
+/**
+ * The context `GalaxyProvider` fills and `useGalaxyTheme()` reads. Undefined outside a provider.
+ * Apps read it through `useGalaxyTheme()`, never directly.
+ */
+export declare const GalaxyThemeContext: import("react").Context<GalaxyThemeContextValue | undefined>;
+/**
+ * @internal The scope a subtree renders in: the theme of the nearest provider or inverse scope.
+ * Read by `useInverseScope` to render the opposite theme, and by a scoped `GalaxyProvider` with
+ * no `theme` to inherit it; never by apps.
+ */
+export interface ThemeScope {
+    /** The theme rendering in this subtree. */
+    base: GalaxyTheme.DARK | GalaxyTheme.LIGHT;
+}
+/** @internal See `ThemeScope`. `undefined` outside a provider. */
+export declare const ThemeScopeContext: import("react").Context<ThemeScope | undefined>;
+/**
+ * Internal: the mount node `GalaxyProvider`'s `portalContainer` supplies to `Portal`. `undefined`
+ * when no provider sets one (`Portal` then uses `document.body`); `null` while the node is not
+ * available yet. Read by `Portal`, never by apps.
+ */
+export declare const PortalContainerContext: import("react").Context<HTMLElement | null | undefined>;
+/**
+ * The resolved theme, and the stored preference and its setter.
+ * Throws when called outside a `GalaxyProvider`.
+ */
+export declare function useGalaxyTheme(): GalaxyThemeContextValue;

package/dist/theme/useGalaxyTheme.js

@@ -0,0 +1,36 @@
+import { createContext, useContext } from "react";
+//#region src/theme/useGalaxyTheme.ts
+/**
+* Read the resolved theme, and change it. For JS logic only (charts, canvas, seeded colors,
+* Storybook): styling never calls this, because components read `var(--gx-…)` and a theme switch
+* is one attribute change on the root.
+*
+* This module owns the contexts (GalaxyProvider Q3 (a)); `GalaxyProvider` supplies the values.
+*/
+/**
+* The context `GalaxyProvider` fills and `useGalaxyTheme()` reads. Undefined outside a provider.
+* Apps read it through `useGalaxyTheme()`, never directly.
+*/
+var GalaxyThemeContext = createContext(void 0);
+GalaxyThemeContext.displayName = "GalaxyThemeContext";
+/** @internal See `ThemeScope`. `undefined` outside a provider. */
+var ThemeScopeContext = createContext(void 0);
+ThemeScopeContext.displayName = "ThemeScopeContext";
+/**
+* Internal: the mount node `GalaxyProvider`'s `portalContainer` supplies to `Portal`. `undefined`
+* when no provider sets one (`Portal` then uses `document.body`); `null` while the node is not
+* available yet. Read by `Portal`, never by apps.
+*/
+var PortalContainerContext = createContext(void 0);
+PortalContainerContext.displayName = "PortalContainerContext";
+/**
+* The resolved theme, and the stored preference and its setter.
+* Throws when called outside a `GalaxyProvider`.
+*/
+function useGalaxyTheme() {
+	const context = useContext(GalaxyThemeContext);
+	if (context === void 0) throw new Error("useGalaxyTheme() must be called inside a GalaxyProvider.");
+	return context;
+}
+//#endregion
+export { GalaxyThemeContext, PortalContainerContext, ThemeScopeContext, useGalaxyTheme };

package/dist/theme/useInverseScope.d.ts

@@ -0,0 +1,18 @@
+import { type ThemeScope } from "./useGalaxyTheme.js";
+/** @internal The attributes that put an element in the inverse scope. */
+export interface InverseScopeAttributes {
+    /** The opposite built-in theme, lowercase. */
+    "data-gx-theme": string;
+}
+/** @internal What `useInverseScope` returns. */
+export interface InverseScopeValue {
+    /** Spread onto the element that becomes the scope. */
+    attributes: InverseScopeAttributes;
+    /** Provide through `ThemeScopeContext` to the scope's children, so a nested scope flips back. */
+    scope: ThemeScope;
+}
+/**
+ * @internal The inverse scope of the nearest provider (outside one: the light theme, the
+ * opposite of the dark default), as attributes plus the scope value for its children.
+ */
+export declare function useInverseScope(): InverseScopeValue;

package/dist/theme/useInverseScope.js

@@ -0,0 +1,33 @@
+import { GalaxyTheme } from "./enums.js";
+import { ThemeScopeContext } from "./useGalaxyTheme.js";
+import { useContext } from "react";
+//#region src/theme/useInverseScope.ts
+/**
+* @internal The inverse scope's attributes (docs/theming.md → The inverse scope): a subtree rendered in
+* the opposite built-in theme. There are no inverse tokens; a component that
+* wants the high-contrast look (the Tooltip bubble; a story-local inverse cell) spreads these
+* attributes on its own element, provides `scope` to its children, and uses the ordinary tokens
+* inside (`background.base`, `text.primary`, …). It sets its own `color: text.primary` so
+* inherited text re-roots in the scope.
+*
+* No CSS lives here, so modules in the Text ↔ Tooltip ↔ Kbd cycle can import it without
+* reordering `styles.css`. Never used by apps.
+*/
+/** The built-in theme opposite each base. */
+var BASE_TO_INVERSE_MAP = {
+	[GalaxyTheme.DARK]: GalaxyTheme.LIGHT,
+	[GalaxyTheme.LIGHT]: GalaxyTheme.DARK
+};
+/**
+* @internal The inverse scope of the nearest provider (outside one: the light theme, the
+* opposite of the dark default), as attributes plus the scope value for its children.
+*/
+function useInverseScope() {
+	const base = BASE_TO_INVERSE_MAP[useContext(ThemeScopeContext)?.base ?? GalaxyTheme.DARK];
+	return {
+		attributes: { "data-gx-theme": base.toLowerCase() },
+		scope: { base }
+	};
+}
+//#endregion
+export { useInverseScope };

package/dist/three/GalaxyLogomark3D.d.ts

@@ -0,0 +1,46 @@
+import { type AriaAttributes, type CSSProperties } from "react";
+export interface GalaxyLogomark3DProps extends AriaAttributes {
+    /**
+     * Width and height of the square canvas in px.
+     * @default 128
+     */
+    size?: number;
+    /**
+     * For a mark on an inverted fill (`text.primary`): the material takes `background.base` instead of `text.primary`.
+     * @default false
+     */
+    isInverse?: boolean;
+    /**
+     * Spin continuously around the vertical axis at `speed`.
+     * @default false
+     */
+    isAutoRotate?: boolean;
+    /**
+     * Let the user drag to orbit the mark. There is no zoom or pan.
+     * @default false
+     */
+    isInteractive?: boolean;
+    /**
+     * Do a quick double flip on random axes when the pointer enters.
+     * @default false
+     */
+    isHoverable?: boolean;
+    /**
+     * Auto-rotation rate in radians per second. The hover flip lasts `0.5 / speed` seconds.
+     * @default 2
+     */
+    speed?: number;
+    /** Accessible name. Without it the mark is decorative (`aria-hidden`). */
+    ariaLabel?: string;
+    /** DOM id on the root `<span>`. */
+    id?: string;
+    /** Any `data-*` attribute, forwarded to the root `<span>`. */
+    [dataAttribute: `data-${string}`]: string | number | boolean | undefined;
+    /** Extra class on the root `<span>`. */
+    className?: string;
+    /** Inline style on the root, merged after its own `--gx-galaxy-logomark-3d-size`. */
+    style?: CSSProperties;
+}
+/** The Galaxy mark in 3D, painted `text.primary`. Decorative unless `ariaLabel` is set. */
+declare const GalaxyLogomark3D: import("react").ForwardRefExoticComponent<GalaxyLogomark3DProps & import("react").RefAttributes<HTMLSpanElement>>;
+export default GalaxyLogomark3D;

package/dist/three/GalaxyLogomark3D.js

@@ -0,0 +1,134 @@
+import { useGalaxyTheme } from "../theme/useGalaxyTheme.js";
+import { brandMarkAriaProps } from "../brand/brandMark.js";
+import GalaxyLogomark from "../brand/GalaxyLogomark.js";
+import { usePrefersReducedMotion } from "../hooks/usePrefersReducedMotion.js";
+/* empty css                           */
+import { styled } from "@linaria/react";
+import { forwardRef, useEffect, useRef, useState } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { cx } from "@linaria/core";
+//#region src/three/GalaxyLogomark3D.tsx
+/**
+* The Galaxy mark as a lit, glossy 3D object for hero moments (a landing hero, a sign-in splash).
+* It can spin slowly, flip when the pointer arrives, and be dragged to orbit. Its material takes
+* the monochrome fill (`solid.primary.background`, read as resolved hex from `useGalaxyTheme()`
+* because WebGL needs a number, not a CSS variable). It always starts as the flat `GalaxyLogomark`: the server and first
+* client render are the static mark; after mount, if WebGL is available and motion is not reduced,
+* three.js (an optional peer) and the model load lazily and the 3D mark replaces the flat one in
+* the same box. This module imports nothing from three.js; the scene lives behind one `import()`.
+*/
+/**
+* At the 1.x camera (z = 4, fov 45°, mesh scale 0.088) the resting mesh spans ≈ 76% of the
+* canvas; the flat fallback is drawn at that share so the swap has no size jump.
+*/
+var FALLBACK_SCALE = .76;
+/** The box: a square of the requested size; the flat mark centers in it, the canvas covers it. */
+var Root = /*#__PURE__*/ styled("span")({
+	name: "Root",
+	class: "gx-GalaxyLogomark3D-r1dn73it",
+	propsAsIs: false
+});
+/** `isInteractive`: the grab cursor while orbiting is possible. */
+var INTERACTIVE_CSS = "gx-GalaxyLogomark3D-INTERACTIVE_CSS-i13nzb8h";
+/** The WebGL canvas fills the box. */
+var CANVAS_CSS = "gx-GalaxyLogomark3D-CANVAS_CSS-c11hevag";
+/** Until the first frame is drawn, the canvas is laid out but not shown. */
+var CANVAS_HIDDEN_CSS = "gx-GalaxyLogomark3D-CANVAS_HIDDEN_CSS-c1eyhbl2";
+/** Whether this browser can create a WebGL context. Called in an effect, never at import. */
+function isWebGLSupported() {
+	try {
+		const canvas = document.createElement("canvas");
+		return (canvas.getContext("webgl2") ?? canvas.getContext("webgl")) !== null;
+	} catch {
+		return false;
+	}
+}
+/** The Galaxy mark in 3D, painted `text.primary`. Decorative unless `ariaLabel` is set. */
+var GalaxyLogomark3D = forwardRef(function GalaxyLogomark3D({ size = 128, isInverse = false, isAutoRotate = false, isInteractive = false, isHoverable = false, speed = 2, ariaLabel, id, className, style, ...rest }, ref) {
+	const { theme } = useGalaxyTheme();
+	const prefersReducedMotion = usePrefersReducedMotion();
+	const [isWebGLAvailable, setIsWebGLAvailable] = useState(false);
+	const [isReady, setIsReady] = useState(false);
+	const canvasRef = useRef(null);
+	const sceneRef = useRef(null);
+	const color = isInverse ? theme.color.background.base : theme.color.solid.primary.background;
+	const options = {
+		size,
+		color,
+		isAutoRotate,
+		isInteractive,
+		isHoverable,
+		speed
+	};
+	const optionsRef = useRef(options);
+	optionsRef.current = options;
+	useEffect(() => {
+		setIsWebGLAvailable(isWebGLSupported());
+	}, []);
+	const canRender3D = isWebGLAvailable && !prefersReducedMotion;
+	useEffect(() => {
+		const canvas = canvasRef.current;
+		if (!canRender3D || canvas === null) return;
+		let isCancelled = false;
+		const onContextLost = () => setIsReady(false);
+		canvas.addEventListener("webglcontextlost", onContextLost);
+		import("./galaxyLogomark3DScene.js").then(({ mountGalaxyLogomark3DScene }) => {
+			if (isCancelled) return;
+			try {
+				sceneRef.current = mountGalaxyLogomark3DScene(canvas, optionsRef.current, () => {
+					if (!isCancelled) setIsReady(true);
+				});
+			} catch {}
+		}, () => {});
+		return () => {
+			isCancelled = true;
+			canvas.removeEventListener("webglcontextlost", onContextLost);
+			sceneRef.current?.dispose();
+			sceneRef.current = null;
+			setIsReady(false);
+		};
+	}, [canRender3D]);
+	useEffect(() => {
+		sceneRef.current?.update({
+			size,
+			color,
+			isAutoRotate,
+			isInteractive,
+			isHoverable,
+			speed
+		});
+	}, [
+		size,
+		color,
+		isAutoRotate,
+		isInteractive,
+		isHoverable,
+		speed
+	]);
+	const aria = brandMarkAriaProps(ariaLabel ?? rest["aria-label"]);
+	const variables = { "--gx-galaxy-logomark-3d-size": `${size}px` };
+	return /* @__PURE__ */ jsxs(Root, {
+		ref,
+		id,
+		role: aria.role,
+		"aria-label": aria["aria-label"],
+		"aria-hidden": aria["aria-hidden"],
+		...rest,
+		className: cx(isInteractive && INTERACTIVE_CSS, className),
+		style: {
+			...variables,
+			...style
+		},
+		children: [!isReady && /* @__PURE__ */ jsx(GalaxyLogomark, {
+			size: Math.round(size * FALLBACK_SCALE),
+			isInverse
+		}), canRender3D && /* @__PURE__ */ jsx("canvas", {
+			ref: canvasRef,
+			"aria-hidden": true,
+			className: cx(CANVAS_CSS, !isReady && CANVAS_HIDDEN_CSS)
+		})]
+	});
+});
+GalaxyLogomark3D.displayName = "GalaxyLogomark3D";
+//#endregion
+export { GalaxyLogomark3D as default };