@atom-learning/components 11.6.0 → 12.0.0-beta.2

package/dist/experiments/theme/Theme.d.ts

@@ -0,0 +1,60 @@
+import * as React from 'react';
+export type TColorScheme = 'light' | 'dark' | 'system';
+export type TColorBrand = 'atom' | 'school' | 'quest';
+export type TColorPalette = 'default' | 'rose' | 'sage';
+export type TBrandPalette = {
+    atom: 'default' | 'rose' | 'sage';
+    school: 'default' | 'rose';
+    quest: 'default';
+};
+export type TColorAccent = 'grey' | 'brand' | 'blue' | 'pink' | 'marsh' | 'green' | 'red' | 'orange' | 'purple' | 'cyan' | 'teal' | 'magenta' | 'lime' | 'lapis' | 'maroon' | 'emerald' | 'yellow' | 'success' | 'danger' | 'warning' | 'info';
+export type TColorHue = Exclude<TColorAccent, 'success' | 'danger' | 'warning' | 'info'>;
+type TThemeValue = {
+    colorScheme?: TColorScheme;
+    brand?: TColorBrand;
+    palette?: TColorPalette;
+    accent?: TColorAccent;
+};
+type ThemeProps = React.HTMLAttributes<HTMLDivElement> & Omit<TThemeValue, 'accent'> & {
+    accent?: TColorHue;
+    asChild?: boolean;
+    ref?: React.Ref<HTMLDivElement>;
+};
+/**
+ * @experimental Theming prototype. Unset props inherit from the nearest ancestor.
+ */
+export declare const Theme: ({ colorScheme, brand, palette, accent, asChild, ...rest }: ThemeProps) => React.JSX.Element;
+/** Re-applies the surrounding <Theme> inside a portal. */
+export declare const ThemePortalScope: ({ children }: {
+    children: React.ReactNode;
+}) => string | number | bigint | boolean | React.JSX.Element | Iterable<React.ReactNode> | Promise<string | number | bigint | boolean | Iterable<React.ReactNode> | React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | React.ReactPortal | null | undefined> | null | undefined;
+/**
+ * The colour scheme actually rendered here: the nearest <Theme>, else the
+ * <html> attribute, with `system` resolved against the OS. Renders 'light' on
+ * the server for `system`, as the OS preference is unknown there.
+ */
+export declare const useColorScheme: () => 'light' | 'dark';
+/** The palette rendered here: the nearest <Theme>, else the <html> attribute. */
+export declare const useColorPalette: () => TColorPalette;
+/**
+ * Resolved values of CSS variables at `ref`, for libraries that need real
+ * colours rather than `var()` strings (charts, canvas). Read from the element
+ * itself so nested scopes apply, and re-read when the scheme, brand, palette
+ * or accent change. Empty until the element mounts.
+ */
+export declare const useResolvedColors: <T extends string>(ref: React.RefObject<Element | null>, names: readonly T[]) => Partial<Record<T, string>>;
+/**
+ * Inline <head> script that sets data-color-scheme before first paint. The app
+ * owns the flag and storage: only an explicit 'light' or 'dark' is honoured from
+ * storage, anything else means system.
+ */
+export declare const getColorSchemeScript: ({ enabled, storageKey }: {
+    enabled: boolean;
+    storageKey: string;
+}) => string;
+/**
+ * Runs a scheme or palette change without CSS transitions, so components with
+ * transition-colors don't all animate to their new colours.
+ */
+export declare const withoutTransitions: (change: () => void) => void;
+export {};

package/dist/experiments/theme/Theme.js

@@ -0,0 +1,131 @@
+import * as React$1 from "react";
+import { jsx } from "react/jsx-runtime";
+import { Slot } from "@radix-ui/react-slot";
+//#region src/experiments/theme/Theme.tsx
+var ThemeContext = React$1.createContext({});
+var toAttributes = ({ colorScheme, brand, palette, accent }) => ({
+	"data-color-scheme": colorScheme,
+	"data-brand": brand,
+	"data-color-palette": palette,
+	"data-color-accent": accent
+});
+/**
+* @experimental Theming prototype. Unset props inherit from the nearest ancestor.
+*/
+var Theme = ({ colorScheme, brand, palette, accent, asChild = false, ...rest }) => {
+	const parent = React$1.use(ThemeContext);
+	return /* @__PURE__ */ jsx(ThemeContext, {
+		value: React$1.useMemo(() => ({
+			colorScheme: colorScheme ?? parent.colorScheme,
+			brand: brand ?? parent.brand,
+			palette: palette ?? (brand ? "default" : parent.palette),
+			accent: accent ?? (palette || brand ? void 0 : parent.accent)
+		}), [
+			colorScheme,
+			brand,
+			palette,
+			accent,
+			parent
+		]),
+		children: /* @__PURE__ */ jsx(asChild ? Slot : "div", {
+			...toAttributes({
+				colorScheme,
+				brand,
+				palette,
+				accent
+			}),
+			...rest
+		})
+	});
+};
+/** Re-applies the surrounding <Theme> inside a portal. */
+var ThemePortalScope = ({ children }) => {
+	const value = React$1.use(ThemeContext);
+	if (!value.colorScheme && !value.brand && !value.palette && !value.accent) return children;
+	return /* @__PURE__ */ jsx("div", {
+		className: "contents",
+		...toAttributes(value),
+		children
+	});
+};
+var subscribeToRoot = (onChange) => {
+	const observer = new MutationObserver(onChange);
+	observer.observe(document.documentElement, { attributeFilter: ["data-color-scheme", "data-color-palette"] });
+	return () => observer.disconnect();
+};
+var useRootAttribute = (name) => React$1.useSyncExternalStore(subscribeToRoot, () => document.documentElement.getAttribute(name), () => null);
+var darkQuery = "(prefers-color-scheme: dark)";
+var subscribeToOs = (onChange) => {
+	const query = window.matchMedia(darkQuery);
+	query.addEventListener("change", onChange);
+	return () => query.removeEventListener("change", onChange);
+};
+/**
+* The colour scheme actually rendered here: the nearest <Theme>, else the
+* <html> attribute, with `system` resolved against the OS. Renders 'light' on
+* the server for `system`, as the OS preference is unknown there.
+*/
+var useColorScheme = () => {
+	const { colorScheme } = React$1.use(ThemeContext);
+	const root = useRootAttribute("data-color-scheme");
+	const osDark = React$1.useSyncExternalStore(subscribeToOs, () => window.matchMedia(darkQuery).matches, () => false);
+	const setting = colorScheme ?? root ?? "light";
+	if (setting === "system") return osDark ? "dark" : "light";
+	return setting === "dark" ? "dark" : "light";
+};
+/** The palette rendered here: the nearest <Theme>, else the <html> attribute. */
+var useColorPalette = () => {
+	const { palette } = React$1.use(ThemeContext);
+	const root = useRootAttribute("data-color-palette");
+	return palette ?? root ?? "default";
+};
+/**
+* Resolved values of CSS variables at `ref`, for libraries that need real
+* colours rather than `var()` strings (charts, canvas). Read from the element
+* itself so nested scopes apply, and re-read when the scheme, brand, palette
+* or accent change. Empty until the element mounts.
+*/
+var useResolvedColors = (ref, names) => {
+	const scheme = useColorScheme();
+	const palette = useColorPalette();
+	const { brand, accent } = React$1.use(ThemeContext);
+	const rootBrand = useRootAttribute("data-brand");
+	const [colors, setColors] = React$1.useState({});
+	const key = names.join(",");
+	React$1.useLayoutEffect(() => {
+		if (!ref.current) return;
+		const style = window.getComputedStyle(ref.current);
+		setColors(Object.fromEntries(key.split(",").map((name) => [name, style.getPropertyValue(name).trim()])));
+	}, [
+		ref,
+		key,
+		scheme,
+		palette,
+		brand,
+		rootBrand,
+		accent
+	]);
+	return colors;
+};
+/**
+* Inline <head> script that sets data-color-scheme before first paint. The app
+* owns the flag and storage: only an explicit 'light' or 'dark' is honoured from
+* storage, anything else means system.
+*/
+var getColorSchemeScript = ({ enabled, storageKey }) => `(()=>{var s;try{s=localStorage.getItem(${JSON.stringify(storageKey)})}catch(e){}document.documentElement.dataset.colorScheme=${enabled}?(s==='light'||s==='dark'?s:'system'):'light'})()`;
+/**
+* Runs a scheme or palette change without CSS transitions, so components with
+* transition-colors don't all animate to their new colours.
+*/
+var withoutTransitions = (change) => {
+	const style = document.createElement("style");
+	style.textContent = "*,*::before,*::after{transition:none!important}";
+	document.head.append(style);
+	change();
+	window.getComputedStyle(document.body).opacity;
+	requestAnimationFrame(() => style.remove());
+};
+//#endregion
+export { Theme, ThemePortalScope, getColorSchemeScript, useColorPalette, useColorScheme, useResolvedColors, withoutTransitions };
+
+//# sourceMappingURL=Theme.js.map

package/dist/experiments/theme/Theme.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Theme.js","names":[],"sources":["../../../src/experiments/theme/Theme.tsx"],"sourcesContent":["import { Slot } from '@radix-ui/react-slot'\nimport * as React from 'react'\n\n// Keep in sync with scripts/generate-color-theme-css.mjs\nexport type TColorScheme = 'light' | 'dark' | 'system'\nexport type TColorBrand = 'atom' | 'school' | 'quest'\nexport type TColorPalette = 'default' | 'rose' | 'sage'\n// The palettes each brand offers. The CSS renders any pairing, so this is\n// where the allow-list is enforced, e.g. in an app's palette picker.\nexport type TBrandPalette = {\n  atom: 'default' | 'rose' | 'sage'\n  school: 'default' | 'rose'\n  quest: 'default'\n}\nexport type TColorAccent =\n  | 'grey'\n  | 'brand'\n  | 'blue'\n  | 'pink'\n  | 'marsh'\n  | 'green'\n  | 'red'\n  | 'orange'\n  | 'purple'\n  | 'cyan'\n  | 'teal'\n  | 'magenta'\n  | 'lime'\n  | 'lapis'\n  | 'maroon'\n  | 'emerald'\n  | 'yellow'\n  | 'success'\n  | 'danger'\n  | 'warning'\n  | 'info'\n\n// Status colours are reached through components' `tone`, never a whole area\nexport type TColorHue = Exclude<\n  TColorAccent,\n  'success' | 'danger' | 'warning' | 'info'\n>\n\ntype TThemeValue = {\n  colorScheme?: TColorScheme\n  brand?: TColorBrand\n  palette?: TColorPalette\n  accent?: TColorAccent\n}\n\n// Carries the effective theme so portalled content, which mounts outside the\n// <Theme> element, can re-apply it.\nconst ThemeContext = React.createContext<TThemeValue>({})\n\nconst toAttributes = ({\n  colorScheme,\n  brand,\n  palette,\n  accent\n}: TThemeValue) => ({\n  'data-color-scheme': colorScheme,\n  'data-brand': brand,\n  'data-color-palette': palette,\n  'data-color-accent': accent\n})\n\ntype ThemeProps = React.HTMLAttributes<HTMLDivElement> &\n  Omit<TThemeValue, 'accent'> & {\n    accent?: TColorHue\n    asChild?: boolean\n    ref?: React.Ref<HTMLDivElement>\n  }\n\n/**\n * @experimental Theming prototype. Unset props inherit from the nearest ancestor.\n */\nexport const Theme = ({\n  colorScheme,\n  brand,\n  palette,\n  accent,\n  asChild = false,\n  ...rest\n}: ThemeProps) => {\n  const parent = React.use(ThemeContext)\n  const value = React.useMemo(\n    () => ({\n      colorScheme: colorScheme ?? parent.colorScheme,\n      brand: brand ?? parent.brand,\n      // A brand starts from its own default palette, as it may not offer the\n      // inherited one; a palette brings its own accent. Either stops inheritance.\n      palette: palette ?? (brand ? 'default' : parent.palette),\n      accent: accent ?? (palette || brand ? undefined : parent.accent)\n    }),\n    [colorScheme, brand, palette, accent, parent]\n  )\n  const Component = asChild ? Slot : 'div'\n\n  return (\n    <ThemeContext value={value}>\n      <Component\n        {...toAttributes({ colorScheme, brand, palette, accent })}\n        {...rest}\n      />\n    </ThemeContext>\n  )\n}\n\n/** Re-applies the surrounding <Theme> inside a portal. */\nexport const ThemePortalScope = ({\n  children\n}: {\n  children: React.ReactNode\n}) => {\n  const value = React.use(ThemeContext)\n  if (!value.colorScheme && !value.brand && !value.palette && !value.accent)\n    return children\n  return (\n    <div className=\"contents\" {...toAttributes(value)}>\n      {children}\n    </div>\n  )\n}\n\n// The app sets the root attributes on <html>, outside React, so observe them.\nconst subscribeToRoot = (onChange: () => void) => {\n  const observer = new MutationObserver(onChange)\n  observer.observe(document.documentElement, {\n    attributeFilter: ['data-color-scheme', 'data-color-palette']\n  })\n  return () => observer.disconnect()\n}\n\nconst useRootAttribute = (name: string) =>\n  React.useSyncExternalStore(\n    subscribeToRoot,\n    () => document.documentElement.getAttribute(name),\n    () => null\n  )\n\nconst darkQuery = '(prefers-color-scheme: dark)'\nconst subscribeToOs = (onChange: () => void) => {\n  const query = window.matchMedia(darkQuery)\n  query.addEventListener('change', onChange)\n  return () => query.removeEventListener('change', onChange)\n}\n\n/**\n * The colour scheme actually rendered here: the nearest <Theme>, else the\n * <html> attribute, with `system` resolved against the OS. Renders 'light' on\n * the server for `system`, as the OS preference is unknown there.\n */\nexport const useColorScheme = (): 'light' | 'dark' => {\n  const { colorScheme } = React.use(ThemeContext)\n  const root = useRootAttribute('data-color-scheme')\n  const osDark = React.useSyncExternalStore(\n    subscribeToOs,\n    () => window.matchMedia(darkQuery).matches,\n    () => false\n  )\n  const setting = colorScheme ?? root ?? 'light'\n  if (setting === 'system') return osDark ? 'dark' : 'light'\n  return setting === 'dark' ? 'dark' : 'light'\n}\n\n/** The palette rendered here: the nearest <Theme>, else the <html> attribute. */\nexport const useColorPalette = (): TColorPalette => {\n  const { palette } = React.use(ThemeContext)\n  const root = useRootAttribute('data-color-palette')\n  return palette ?? (root as TColorPalette | null) ?? 'default'\n}\n\n/**\n * Resolved values of CSS variables at `ref`, for libraries that need real\n * colours rather than `var()` strings (charts, canvas). Read from the element\n * itself so nested scopes apply, and re-read when the scheme, brand, palette\n * or accent change. Empty until the element mounts.\n */\nexport const useResolvedColors = <T extends string>(\n  ref: React.RefObject<Element | null>,\n  names: readonly T[]\n): Partial<Record<T, string>> => {\n  const scheme = useColorScheme()\n  const palette = useColorPalette()\n  const { brand, accent } = React.use(ThemeContext)\n  const rootBrand = useRootAttribute('data-brand')\n  const [colors, setColors] = React.useState<Partial<Record<T, string>>>({})\n  const key = names.join(',')\n\n  React.useLayoutEffect(() => {\n    if (!ref.current) return\n    const style = window.getComputedStyle(ref.current)\n    setColors(\n      Object.fromEntries(\n        key\n          .split(',')\n          .map((name) => [name, style.getPropertyValue(name).trim()])\n      ) as Partial<Record<T, string>>\n    )\n  }, [ref, key, scheme, palette, brand, rootBrand, accent])\n\n  return colors\n}\n\n/**\n * Inline <head> script that sets data-color-scheme before first paint. The app\n * owns the flag and storage: only an explicit 'light' or 'dark' is honoured from\n * storage, anything else means system.\n */\nexport const getColorSchemeScript = ({\n  enabled,\n  storageKey\n}: {\n  enabled: boolean\n  storageKey: string\n}) =>\n  `(()=>{var s;try{s=localStorage.getItem(${JSON.stringify(storageKey)})}catch(e){}` +\n  `document.documentElement.dataset.colorScheme=${enabled}?(s==='light'||s==='dark'?s:'system'):'light'})()`\n\n/**\n * Runs a scheme or palette change without CSS transitions, so components with\n * transition-colors don't all animate to their new colours.\n */\nexport const withoutTransitions = (change: () => void) => {\n  const style = document.createElement('style')\n  style.textContent = '*,*::before,*::after{transition:none!important}'\n  document.head.append(style)\n  change()\n  // Force a style recalc so the change lands while transitions are off\n  void window.getComputedStyle(document.body).opacity\n  requestAnimationFrame(() => style.remove())\n}\n"],"mappings":"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"}