@galaxy-io/dls 1.4.10 → 1.4.12

package/dist/text/HotKeys.d.ts

@@ -1,3 +1,4 @@
+/** Key-cap contrast. Step it down when the shortcut is secondary to its label. */
 export declare enum HotKeysVariant {
     BASE = "BASE",
     PRIMARY = "PRIMARY",
@@ -5,16 +6,25 @@ export declare enum HotKeysVariant {
     TERTIARY = "TERTIARY",
     DISABLED = "DISABLED"
 }
+/** Key-cap size — 14 / 16 / 18px minimum width. Match the adjacent text. */
 export declare enum HotKeysSize {
     SMALL = "SMALL",
     MEDIUM = "MEDIUM",
     LARGE = "LARGE"
 }
 export interface HotKeysProps {
+    /** One cap per entry, in press order — e.g. `["⌘", "K"]`. Rendered verbatim. */
     hotKeys: string[];
+    /** @default HotKeysVariant.BASE */
     variant?: HotKeysVariant;
+    /** @default HotKeysSize.MEDIUM */
     size?: HotKeysSize;
+    /** Render caps in the mono family. */
     isMonospace?: boolean;
 }
+/**
+ * Renders a keyboard shortcut as a row of key caps. Display only — it does not
+ * bind anything; wire the actual handler yourself.
+ */
 declare const HotKeys: ({ hotKeys, variant, size, isMonospace, }: HotKeysProps) => import("react").JSX.Element;
 export default HotKeys;

package/dist/text/HotKeys.js

@@ -4,6 +4,7 @@ import { styled } from "@linaria/react";
 import { match } from "ts-pattern";
 import { jsx } from "react/jsx-runtime";
 //#region src/text/HotKeys.tsx
+/** Key-cap contrast. Step it down when the shortcut is secondary to its label. */
 var HotKeysVariant = /* @__PURE__ */ function(HotKeysVariant) {
 	HotKeysVariant["BASE"] = "BASE";
 	HotKeysVariant["PRIMARY"] = "PRIMARY";
@@ -12,6 +13,7 @@ var HotKeysVariant = /* @__PURE__ */ function(HotKeysVariant) {
 	HotKeysVariant["DISABLED"] = "DISABLED";
 	return HotKeysVariant;
 }({});
+/** Key-cap size — 14 / 16 / 18px minimum width. Match the adjacent text. */
 var HotKeysSize = /* @__PURE__ */ function(HotKeysSize) {
 	HotKeysSize["SMALL"] = "SMALL";
 	HotKeysSize["MEDIUM"] = "MEDIUM";
@@ -56,6 +58,10 @@ var StyledHotKey = withTheme(/*#__PURE__*/ styled("div")({
 		"sl247mt-7": [_exp9()]
 	}
 }));
+/**
+* Renders a keyboard shortcut as a row of key caps. Display only — it does not
+* bind anything; wire the actual handler yourself.
+*/
 var HotKeys = ({ hotKeys, variant, size = "MEDIUM", isMonospace = false }) => {
 	return /* @__PURE__ */ jsx(HotKeysWrapper, { children: hotKeys.map((hotKey) => /* @__PURE__ */ jsx(StyledHotKey, {
 		$variant: variant,

package/dist/text/MarkdownText.d.ts

@@ -1,7 +1,15 @@
 import { type Components } from "react-markdown";
-interface MarkdownTextProps {
+export interface MarkdownTextProps {
+    /** Markdown source. GitHub-flavored, and raw HTML is allowed through. */
     content: string;
+    /** Replace the renderer for specific tags. Merged over the DLS defaults. */
     componentOverrides?: Partial<Components>;
 }
+/**
+ * Renders Markdown using DLS components — headings, lists, tables and code all
+ * come out on theme tokens rather than browser defaults.
+ *
+ * Raw HTML in `content` is rendered, not escaped. Don't pass untrusted input.
+ */
 declare const MarkdownText: ({ content, componentOverrides }: MarkdownTextProps) => import("react").JSX.Element;
 export default MarkdownText;

package/dist/text/MarkdownText.js

@@ -297,6 +297,12 @@ var markdownComponents = {
 		children
 	})
 };
+/**
+* Renders Markdown using DLS components — headings, lists, tables and code all
+* come out on theme tokens rather than browser defaults.
+*
+* Raw HTML in `content` is rendered, not escaped. Don't pass untrusted input.
+*/
 var MarkdownText = ({ content, componentOverrides }) => {
 	const components = componentOverrides ? {
 		...markdownComponents,

package/dist/text/Paragraph.d.ts

@@ -1,16 +1,33 @@
 import type { CSSProperties, PropsWithChildren } from "react";
 import { TextSize, TextVariant, TextWeight } from "./Text";
 export interface ParagraphProps {
+    /** Color role. @default TextVariant.PRIMARY */
     variant?: TextVariant;
+    /** Type scale step. @default TextSize.BODY_MD */
     size?: TextSize;
+    /** @default TextWeight.REGULAR */
     weight?: TextWeight;
+    /** @default "left" */
     align?: CSSProperties["textAlign"];
+    /** Cursor over the text. Inherits from the parent when unset. */
     cursor?: CSSProperties["cursor"];
+    /** Raw color that bypasses `variant`. Escape hatch — prefer `variant`. */
     hex?: string;
+    /** Render in the mono family (Berkeley Mono) instead of sans. */
     isMonospace?: boolean;
+    /** Let the user select the text. Off by default so UI chrome isn't selectable. */
     isSelectable?: boolean;
+    /** Truncate after this many lines with an ellipsis. Omit to let it run. */
     lineClamp?: number;
+    /** Reserve height so clamped copy doesn't shift layout. Defaults to `lineClamp` em. */
     minHeight?: string;
 }
+/**
+ * Multi-line body copy. Same tokens as `Text`, but with a 1.25× line height for
+ * readability and `lineClamp` instead of single-line ellipsis.
+ *
+ * Use `Text` for labels and single-line UI strings; reach for this when the copy
+ * is a real paragraph.
+ */
 declare const Paragraph: ({ children, size, variant, weight, align, cursor, isMonospace, isSelectable, lineClamp, minHeight, hex, }: PropsWithChildren<ParagraphProps>) => import("react").JSX.Element;
 export default Paragraph;

package/dist/text/Paragraph.js

@@ -57,6 +57,13 @@ var StyledParagraph = withTheme(/*#__PURE__*/ styled("span")({
 		"sts1mtj-14": [_exp16()]
 	}
 }));
+/**
+* Multi-line body copy. Same tokens as `Text`, but with a 1.25× line height for
+* readability and `lineClamp` instead of single-line ellipsis.
+*
+* Use `Text` for labels and single-line UI strings; reach for this when the copy
+* is a real paragraph.
+*/
 var Paragraph = ({ children, size = TextSize.BODY_MD, variant = TextVariant.PRIMARY, weight = TextWeight.REGULAR, align = "left", cursor, isMonospace = false, isSelectable = false, lineClamp, minHeight, hex }) => {
 	return /* @__PURE__ */ jsx(StyledParagraph, {
 		$size: size,

package/dist/text/RequiredMarker.d.ts

@@ -1,6 +1,8 @@
 import { TextSize } from "./Text";
-interface RequiredMarkerProps {
+export interface RequiredMarkerProps {
+    /** Match the size of the label it sits beside. @default TextSize.BODY_MD */
     size?: TextSize;
 }
+/** The red asterisk marking a required field. Inputs render it from `isRequired`. */
 declare const RequiredMarker: ({ size }: RequiredMarkerProps) => import("react").JSX.Element;
 export default RequiredMarker;

package/dist/text/RequiredMarker.js

@@ -34,6 +34,7 @@ var StyledRequiredMarker = withTheme(/*#__PURE__*/ styled("span")({
 		"s1i18c6k-5": [_exp6()]
 	}
 }));
+/** The red asterisk marking a required field. Inputs render it from `isRequired`. */
 var RequiredMarker = ({ size = TextSize.BODY_MD }) => {
 	return /* @__PURE__ */ jsx(StyledRequiredMarker, {
 		$size: size,

package/dist/text/Selectable.d.ts

@@ -1,3 +1,7 @@
 import type { PropsWithChildren } from "react";
+/**
+ * Makes its children selectable. DLS text is `user-select: none` by default so
+ * UI chrome doesn't highlight — wrap the parts a user should be able to copy.
+ */
 declare const Selectable: ({ children }: PropsWithChildren) => import("react").JSX.Element;
 export default Selectable;

package/dist/text/Selectable.js

@@ -8,6 +8,10 @@ var StyledSelectable = withTheme(/*#__PURE__*/ styled("span")({
 	class: "sfziwh",
 	propsAsIs: false
 }));
+/**
+* Makes its children selectable. DLS text is `user-select: none` by default so
+* UI chrome doesn't highlight — wrap the parts a user should be able to copy.
+*/
 var Selectable = ({ children }) => {
 	return /* @__PURE__ */ jsx(StyledSelectable, { children });
 };

package/dist/text/Text.d.ts

@@ -1,4 +1,5 @@
 import type { CSSProperties, PropsWithChildren } from "react";
+/** Text color role. Resolves to a `theme.color.text.*` token in both themes. */
 export declare enum TextVariant {
     PRIMARY = "PRIMARY",
     PRIMARY_ALT = "PRIMARY_ALT",
@@ -18,6 +19,7 @@ export declare enum TextVariant {
     PURPLE = "PURPLE",
     DISABLED = "DISABLED"
 }
+/** Type scale step. Sets font-size, line-height and letter-spacing together. */
 export declare enum TextSize {
     CAPTION = "CAPTION",
     BODY_SM = "BODY_SM",
@@ -27,21 +29,38 @@ export declare enum TextSize {
     HEADING_MD = "HEADING_MD",
     HEADING_LG = "HEADING_LG"
 }
+/** Font weight. Two steps by design — hierarchy comes from size, not weight. */
 export declare enum TextWeight {
     REGULAR = "REGULAR",
     MEDIUM = "MEDIUM"
 }
 export interface TextProps {
+    /** Color role. @default TextVariant.PRIMARY */
     variant?: TextVariant;
+    /** Type scale step. @default TextSize.BODY_MD */
     size?: TextSize;
+    /** @default TextWeight.REGULAR */
     weight?: TextWeight;
+    /** @default "left" */
     align?: CSSProperties["textAlign"];
+    /** Cursor over the text. Inherits from the parent when unset. */
     cursor?: CSSProperties["cursor"];
+    /** Raw color that bypasses `variant`. Escape hatch — prefer `variant`. */
     hex?: string;
+    /** Render in the mono family (Berkeley Mono) instead of sans. */
     isMonospace?: boolean;
+    /** Let the user select the text. Off by default so UI chrome isn't selectable. */
     isSelectable?: boolean;
     isUnderlined?: boolean;
+    /** Truncate to one line with an ellipsis. Needs a width-bounded parent. */
     isEllipsis?: boolean;
 }
+/**
+ * The text primitive. Every string in a Galaxy UI renders through it, so color,
+ * size and weight always resolve from theme tokens rather than raw CSS.
+ *
+ * Renders a `<p>`. For inline treatments nest `Bold`, `Code`, `Selectable` or
+ * `HotKeys` inside it rather than reaching for a raw tag.
+ */
 declare const Text: ({ children, size, variant, weight, align, cursor, isMonospace, isSelectable, isUnderlined, isEllipsis, hex, }: PropsWithChildren<TextProps>) => import("react").JSX.Element;
 export default Text;

package/dist/text/Text.js

@@ -4,6 +4,7 @@ import { styled } from "@linaria/react";
 import { match } from "ts-pattern";
 import { jsx } from "react/jsx-runtime";
 //#region src/text/Text.tsx
+/** Text color role. Resolves to a `theme.color.text.*` token in both themes. */
 var TextVariant = /* @__PURE__ */ function(TextVariant) {
 	TextVariant["PRIMARY"] = "PRIMARY";
 	TextVariant["PRIMARY_ALT"] = "PRIMARY_ALT";
@@ -24,6 +25,7 @@ var TextVariant = /* @__PURE__ */ function(TextVariant) {
 	TextVariant["DISABLED"] = "DISABLED";
 	return TextVariant;
 }({});
+/** Type scale step. Sets font-size, line-height and letter-spacing together. */
 var TextSize = /* @__PURE__ */ function(TextSize) {
 	TextSize["CAPTION"] = "CAPTION";
 	TextSize["BODY_SM"] = "BODY_SM";
@@ -34,6 +36,7 @@ var TextSize = /* @__PURE__ */ function(TextSize) {
 	TextSize["HEADING_LG"] = "HEADING_LG";
 	return TextSize;
 }({});
+/** Font weight. Two steps by design — hierarchy comes from size, not weight. */
 var TextWeight = /* @__PURE__ */ function(TextWeight) {
 	TextWeight["REGULAR"] = "REGULAR";
 	TextWeight["MEDIUM"] = "MEDIUM";
@@ -85,6 +88,13 @@ var StyledText = withTheme(/*#__PURE__*/ styled("p")({
 		"shbcgkd-13": [_exp15()]
 	}
 }));
+/**
+* The text primitive. Every string in a Galaxy UI renders through it, so color,
+* size and weight always resolve from theme tokens rather than raw CSS.
+*
+* Renders a `<p>`. For inline treatments nest `Bold`, `Code`, `Selectable` or
+* `HotKeys` inside it rather than reaching for a raw tag.
+*/
 var Text = ({ children, size = "BODY_MD", variant = "PRIMARY", weight = "REGULAR", align = "left", cursor, isMonospace = false, isSelectable = false, isUnderlined = false, isEllipsis = false, hex }) => {
 	return /* @__PURE__ */ jsx(StyledText, {
 		$size: size,

package/dist/text/TextShimmer.d.ts

@@ -1,7 +1,14 @@
 export interface TextShimmerProps {
+    /** A number is px. Match the line height of the text being stood in for. */
     height: number | string;
+    /** A number is px. */
     width: number | string;
+    /** Render square corners instead of the default 4px radius. */
     noBorderRadius?: boolean;
 }
+/**
+ * A shimmering placeholder bar for text that hasn't loaded. Size it to the copy
+ * it replaces so the layout doesn't jump when the real text arrives.
+ */
 declare const TextShimmer: ({ height, width, noBorderRadius }: TextShimmerProps) => import("react").JSX.Element;
 export default TextShimmer;

package/dist/text/TextShimmer.js

@@ -19,6 +19,10 @@ var StyledTextShimmer = withTheme(/*#__PURE__*/ styled("span")({
 		"s1p67zkf-3": [_exp6()]
 	}
 }));
+/**
+* A shimmering placeholder bar for text that hasn't loaded. Size it to the copy
+* it replaces so the layout doesn't jump when the real text arrives.
+*/
 var TextShimmer = ({ height, width, noBorderRadius }) => {
 	return /* @__PURE__ */ jsx(StyledTextShimmer, {
 		$height: height,

package/dist/theme/GalaxyTheme.d.ts

@@ -1,6 +1,5 @@
 import { type PropsWithChildren } from "react";
-import { GalaxyTheme } from "./constants";
-import type { Theme } from "./types";
+import { GalaxyTheme, type Theme } from "./types";
 declare const ThemeProvider: import("react").ComponentType<{
     children: React.ReactNode;
     theme?: Theme | undefined;
@@ -9,28 +8,60 @@ declare const ThemeProvider: import("react").ComponentType<{
 }, C>(WrappedComponent: import("react").ComponentType<Props> & C) => import("react").ComponentType<import("@callstack/react-theme-provider").$Without<Props, "theme"> & {
     theme?: import("@callstack/react-theme-provider").$DeepPartial<Theme> | undefined;
 }> & import("@callstack/react-theme-provider/typings/hoist-non-react-statics").NonReactStatics<import("react").ComponentType<Props> & C, {}>, useTheme: <T = Theme>(overrides?: import("@callstack/react-theme-provider").$DeepPartial<T> | undefined) => T;
+/**
+ * How the provider learns the OS theme. Supply your own on platforms where
+ * `prefers-color-scheme` isn't the source of truth (Electron, React Native).
+ */
 export interface ThemeDetector {
+    /** Read the OS theme once, at mount. */
     detectInitialTheme(): Promise<GalaxyTheme.DARK | GalaxyTheme.LIGHT>;
+    /** Subscribe to OS theme changes. Returns an unsubscribe function. */
     onThemeChange(callback: (theme: GalaxyTheme.DARK | GalaxyTheme.LIGHT) => void): () => void;
 }
+/** Default detector — reads `prefers-color-scheme`. Falls back to DARK off-browser. */
 export declare const BrowserThemeDetector: ThemeDetector;
-interface GalaxyThemeContextValue {
+/** What `useGalaxyTheme()` returns. */
+export interface GalaxyThemeContextValue {
+    /** The resolved token set. Read colors and fonts from here. */
     theme: Theme;
+    /** The theme actually rendering. Never `SYSTEM` — that's already resolved. */
     activeTheme: Exclude<GalaxyTheme, GalaxyTheme.SYSTEM>;
+    /** The user's stored preference. Can be `SYSTEM`. Bind theme pickers to this. */
     selectedTheme: GalaxyTheme;
+    /** What the OS reports. Use it to label "System (Dark)" in a picker. */
     systemTheme: GalaxyTheme.DARK | GalaxyTheme.LIGHT;
+    /** Whether the detector can read an OS theme at all. */
     isSystemThemeSupported: boolean;
+    /** Update the preference. Persists through `storage` when one is supplied. */
     setTheme: (theme: GalaxyTheme) => void;
 }
-interface GalaxyThemeProviderProps {
+export interface GalaxyThemeProviderProps {
+    /** Theme to start on when nothing is stored. @default GalaxyTheme.SYSTEM */
     initialTheme?: GalaxyTheme;
+    /** Key the preference is stored under. @default "galaxy-theme" */
     storageKey?: string;
+    /** How the OS theme is read. @default BrowserThemeDetector */
     themeDetector?: ThemeDetector;
+    /**
+     * Where the preference persists. Omit and the choice is lost on reload.
+     * Pass your own adapter — DLS never touches `localStorage` directly, so it
+     * stays safe to render on a server.
+     */
     storage?: {
         get: (key: string) => GalaxyTheme | null;
         set: (key: string, theme: GalaxyTheme) => void;
     };
 }
+/**
+ * Root provider. Wrap the app once, above everything that renders DLS.
+ *
+ * Resolves `SYSTEM` to the OS theme and feeds the token set to every
+ * `withTheme(styled.x)` component. Without it `useGalaxyTheme()` throws.
+ */
 declare const GalaxyThemeProvider: ({ children, initialTheme, storageKey, themeDetector, storage, }: PropsWithChildren<GalaxyThemeProviderProps>) => import("react").JSX.Element;
+/**
+ * Read the active theme, the user's preference, and `setTheme`.
+ * Throws when called outside a `GalaxyThemeProvider`.
+ */
 export declare const useGalaxyTheme: () => GalaxyThemeContextValue;
 export { GalaxyThemeProvider, ThemeProvider, useTheme, withTheme };

package/dist/theme/GalaxyTheme.js

@@ -1,9 +1,11 @@
-import { DEFAULT_THEME, GALAXY_THEME_MAP, GALAXY_THEME_STORAGE_KEY, GalaxyTheme } from "./constants.js";
+import { GalaxyTheme } from "./types.js";
+import { DEFAULT_THEME, GALAXY_THEME_MAP, GALAXY_THEME_STORAGE_KEY } from "./constants.js";
 import { createContext, useCallback, useContext, useEffect, useMemo, useState } from "react";
 import { createTheming } from "@callstack/react-theme-provider";
 import { jsx } from "react/jsx-runtime";
 //#region src/theme/GalaxyTheme.tsx
 var { ThemeProvider, withTheme, useTheme } = createTheming(DEFAULT_THEME);
+/** Default detector — reads `prefers-color-scheme`. Falls back to DARK off-browser. */
 var BrowserThemeDetector = {
 	detectInitialTheme: () => {
 		if (typeof window !== "undefined" && window.matchMedia) {
@@ -26,6 +28,12 @@ var BrowserThemeDetector = {
 	}
 };
 var GalaxyThemeContext = createContext(void 0);
+/**
+* Root provider. Wrap the app once, above everything that renders DLS.
+*
+* Resolves `SYSTEM` to the OS theme and feeds the token set to every
+* `withTheme(styled.x)` component. Without it `useGalaxyTheme()` throws.
+*/
 var GalaxyThemeProvider = ({ children, initialTheme, storageKey = GALAXY_THEME_STORAGE_KEY, themeDetector = BrowserThemeDetector, storage }) => {
 	const [systemTheme, setSystemTheme] = useState(() => {
 		return GalaxyTheme.DARK;
@@ -98,6 +106,10 @@ var GalaxyThemeProvider = ({ children, initialTheme, storageKey = GALAXY_THEME_S
 		})
 	});
 };
+/**
+* Read the active theme, the user's preference, and `setTheme`.
+* Throws when called outside a `GalaxyThemeProvider`.
+*/
 var useGalaxyTheme = () => {
 	const context = useContext(GalaxyThemeContext);
 	if (context === void 0) throw new Error("useGalaxyTheme must be used within a GalaxyThemeProvider");

package/dist/theme/constants.d.ts

@@ -1,11 +1,6 @@
 import type { SelectInputOption } from "../inputs/SelectInput";
-import type { Theme } from "./types";
+import { GalaxyTheme, type Theme } from "./types";
 export declare const GALAXY_THEME_STORAGE_KEY = "galaxy:theme";
-export declare enum GalaxyTheme {
-    SYSTEM = "SYSTEM",
-    DARK = "DARK",
-    LIGHT = "LIGHT"
-}
 export declare const GALAXY_DARK_THEME: Theme;
 export declare const GALAXY_LIGHT_THEME: Theme;
 export declare const GALAXY_THEME_OPTIONS: SelectInputOption[];

package/dist/theme/constants.js

@@ -1,14 +1,9 @@
+import { GalaxyTheme } from "./types.js";
 import { GALAXY_FONT } from "./typography.js";
 import { GALAXY_DARK_COLOR } from "./variants/dark.js";
 import { GALAXY_LIGHT_COLOR } from "./variants/light.js";
 //#region src/theme/constants.ts
 var GALAXY_THEME_STORAGE_KEY = "galaxy:theme";
-var GalaxyTheme = /* @__PURE__ */ function(GalaxyTheme) {
-	GalaxyTheme["SYSTEM"] = "SYSTEM";
-	GalaxyTheme["DARK"] = "DARK";
-	GalaxyTheme["LIGHT"] = "LIGHT";
-	return GalaxyTheme;
-}({});
 var GALAXY_DARK_THEME = {
 	color: GALAXY_DARK_COLOR,
 	font: GALAXY_FONT
@@ -19,25 +14,25 @@ var GALAXY_LIGHT_THEME = {
 };
 var GALAXY_THEME_OPTIONS = [
 	{
-		id: "SYSTEM",
+		id: GalaxyTheme.SYSTEM,
 		label: "System",
-		value: "SYSTEM"
+		value: GalaxyTheme.SYSTEM
 	},
 	{
-		id: "DARK",
+		id: GalaxyTheme.DARK,
 		label: "Dark",
-		value: "DARK"
+		value: GalaxyTheme.DARK
 	},
 	{
-		id: "LIGHT",
+		id: GalaxyTheme.LIGHT,
 		label: "Light",
-		value: "LIGHT"
+		value: GalaxyTheme.LIGHT
 	}
 ];
 var GALAXY_THEME_MAP = {
-	["DARK"]: GALAXY_DARK_THEME,
-	["LIGHT"]: GALAXY_LIGHT_THEME
+	[GalaxyTheme.DARK]: GALAXY_DARK_THEME,
+	[GalaxyTheme.LIGHT]: GALAXY_LIGHT_THEME
 };
 var DEFAULT_THEME = GALAXY_DARK_THEME;
 //#endregion
-export { DEFAULT_THEME, GALAXY_DARK_THEME, GALAXY_LIGHT_THEME, GALAXY_THEME_MAP, GALAXY_THEME_OPTIONS, GALAXY_THEME_STORAGE_KEY, GalaxyTheme };
+export { DEFAULT_THEME, GALAXY_DARK_THEME, GALAXY_LIGHT_THEME, GALAXY_THEME_MAP, GALAXY_THEME_OPTIONS, GALAXY_THEME_STORAGE_KEY };

package/dist/theme/index.js

@@ -1,6 +1,7 @@
+import { GalaxyTheme } from "./types.js";
 import { GALAXY_FONT } from "./typography.js";
 import { GALAXY_DARK_COLOR } from "./variants/dark.js";
 import { GALAXY_LIGHT_COLOR } from "./variants/light.js";
-import { DEFAULT_THEME, GALAXY_DARK_THEME, GALAXY_LIGHT_THEME, GALAXY_THEME_MAP, GALAXY_THEME_OPTIONS, GALAXY_THEME_STORAGE_KEY, GalaxyTheme } from "./constants.js";
+import { DEFAULT_THEME, GALAXY_DARK_THEME, GALAXY_LIGHT_THEME, GALAXY_THEME_MAP, GALAXY_THEME_OPTIONS, GALAXY_THEME_STORAGE_KEY } from "./constants.js";
 import { BrowserThemeDetector, GalaxyThemeProvider, ThemeProvider, useGalaxyTheme, useTheme, withTheme } from "./GalaxyTheme.js";
 export { BrowserThemeDetector, DEFAULT_THEME, GALAXY_DARK_COLOR, GALAXY_DARK_THEME, GALAXY_FONT, GALAXY_LIGHT_COLOR, GALAXY_LIGHT_THEME, GALAXY_THEME_MAP, GALAXY_THEME_OPTIONS, GALAXY_THEME_STORAGE_KEY, GalaxyTheme, GalaxyThemeProvider, ThemeProvider, useGalaxyTheme, useTheme, withTheme };

package/dist/theme/types.d.ts

@@ -1,3 +1,10 @@
+/** Theme preference. `SYSTEM` follows the OS and resolves to `DARK` or `LIGHT`. */
+export declare enum GalaxyTheme {
+    SYSTEM = "SYSTEM",
+    DARK = "DARK",
+    LIGHT = "LIGHT"
+}
+/** Text colors. Target of `TextVariant`; `*Alt` inverts against the theme. */
 export type ThemeTextColor = {
     primary: string;
     primaryAlt: string;
@@ -20,6 +27,7 @@ export type ThemeTextColor = {
     galaxy: string;
     galaxyAlt: string;
 };
+/** Surface colors. `base`/`primary`/`secondary` are the neutral stack; accents are for status only. */
 export type ThemeBackgroundColor = {
     base: string;
     baseAlt: string;
@@ -54,6 +62,7 @@ export type ThemeBackgroundColor = {
     galaxy: string;
     galaxyAlt: string;
 };
+/** Border colors. Always paired with a `0.5px solid` hairline — DLS uses borders, not shadows. */
 export type ThemeBorderColor = {
     primary: string;
     secondary: string;
@@ -73,6 +82,7 @@ export type ThemeBorderColor = {
     galaxy: string;
     galaxyAlt: string;
 };
+/** Icon colors. Target of `IconVariant`. */
 export type ThemeIconColor = {
     primary: string;
     primaryAlt: string;
@@ -94,6 +104,7 @@ export type ThemeIconColor = {
     galaxy: string;
     galaxyAlt: string;
 };
+/** Black/white overlay tints. `bw<N>` is N% opacity; `*Alt` is the inverse. */
 export type ThemeOpacityColor = {
     bw100: string;
     bw100Alt: string;
@@ -118,10 +129,12 @@ export type ThemeOpacityColor = {
     bw0: string;
     bw0Alt: string;
 };
+/** Numeric font weights. Target of `TextWeight`. */
 export type ThemeFontWeight = {
     regular: number;
     medium: number;
 };
+/** Font sizes per `TextSize` step. */
 export type ThemeFontSize = {
     caption: string;
     body_sm: string;
@@ -131,6 +144,7 @@ export type ThemeFontSize = {
     heading_md: string;
     heading_lg: string;
 };
+/** Line heights per `TextSize` step. */
 export type ThemeFontHeight = {
     caption: string;
     body_sm: string;
@@ -140,6 +154,7 @@ export type ThemeFontHeight = {
     heading_md: string;
     heading_lg: string;
 };
+/** Letter spacing per `TextSize` step. */
 export type ThemeFontSpacing = {
     caption: string;
     body_sm: string;
@@ -149,6 +164,7 @@ export type ThemeFontSpacing = {
     heading_md: string;
     heading_lg: string;
 };
+/** One font family plus its full metric scale. */
 export type ThemeFont = {
     family: string;
     weight: ThemeFontWeight;
@@ -156,6 +172,10 @@ export type ThemeFont = {
     height: ThemeFontHeight;
     spacing: ThemeFontSpacing;
 };
+/**
+ * The resolved token set for the active theme. Reach it via `useGalaxyTheme()`,
+ * or as the `theme` prop inside a `withTheme(styled.x)` component.
+ */
 export type Theme = {
     color: {
         text: ThemeTextColor;
@@ -169,6 +189,7 @@ export type Theme = {
         mono: ThemeFont;
     };
 };
+/** Adds the injected `theme` prop to a styled component's own props. */
 export type PropsWithTheme<P = unknown> = P & {
     theme: Theme;
 };

package/dist/theme/types.js

@@ -0,0 +1,10 @@
+//#region src/theme/types.ts
+/** Theme preference. `SYSTEM` follows the OS and resolves to `DARK` or `LIGHT`. */
+var GalaxyTheme = /* @__PURE__ */ function(GalaxyTheme) {
+	GalaxyTheme["SYSTEM"] = "SYSTEM";
+	GalaxyTheme["DARK"] = "DARK";
+	GalaxyTheme["LIGHT"] = "LIGHT";
+	return GalaxyTheme;
+}({});
+//#endregion
+export { GalaxyTheme };

package/dist/toast/Toast.d.ts

@@ -1,5 +1,6 @@
 import type { Icon as PhosphorIcon } from "@phosphor-icons/react";
 import { ButtonProps } from "../buttons/Button";
+/** Severity. Sets the border tint and the default icon. */
 export declare enum ToastVariant {
     PRIMARY = "PRIMARY",
     SUCCESS = "SUCCESS",
@@ -7,12 +8,22 @@ export declare enum ToastVariant {
     ERROR = "ERROR"
 }
 export interface ToastProps {
+    /** @default ToastVariant.PRIMARY */
     variant?: ToastVariant;
+    /** Overrides the icon the variant would pick. Pass the component, not an element. */
     icon?: PhosphorIcon;
+    /** Headline. A string is wrapped in `Text`; a node renders as-is. */
     header: string | React.ReactNode;
+    /** Supporting line under the header. */
     subheader: string | React.ReactNode;
+    /** Buttons in a row along the bottom. Each entry is full `ButtonProps`. */
     actions?: ButtonProps[];
+    /** Adds a dismiss ×. `ToastProvider` supplies this — don't set it by hand. */
     onClose?: () => void;
 }
+/**
+ * The toast card itself. You rarely render this directly — call `showToast`
+ * from `useToast()` and let `ToastProvider` mount, stack and time it out.
+ */
 declare const Toast: ({ variant, icon, header, subheader, actions, onClose, }: ToastProps) => import("react").JSX.Element;
 export default Toast;

package/dist/toast/Toast.js

@@ -10,6 +10,7 @@ import { match } from "ts-pattern";
 import { jsx, jsxs } from "react/jsx-runtime";
 import { CheckCircleIcon, SpinnerGapIcon, WarningIcon, XIcon } from "@phosphor-icons/react";
 //#region src/toast/Toast.tsx
+/** Severity. Sets the border tint and the default icon. */
 var ToastVariant = /* @__PURE__ */ function(ToastVariant) {
 	ToastVariant["PRIMARY"] = "PRIMARY";
 	ToastVariant["SUCCESS"] = "SUCCESS";
@@ -30,6 +31,10 @@ var StyledToast = withTheme(/*#__PURE__*/ styled("div")({
 		"sgmrm4-2": [_exp3()]
 	}
 }));
+/**
+* The toast card itself. You rarely render this directly — call `showToast`
+* from `useToast()` and let `ToastProvider` mount, stack and time it out.
+*/
 var Toast = ({ variant = "PRIMARY", icon, header, subheader, actions, onClose }) => {
 	const renderIcon = () => {
 		if (icon) return /* @__PURE__ */ jsx(Icon, {