@pantheon-systems/pds-toolkit-react 2.0.0-alpha.44 → 2.0.0-alpha.45

package/dist/index.source.d.ts

@@ -120,6 +120,7 @@ export * from './libs/types/custom-types';
 export * from './libs/types/input-types';
 export * from './libs/types/layout-types';
 export * from './libs/types/navigation-types';
+export * from './utilities/context-providers/ThemeContext/ThemeContext';
 export * from './utilities/grid/Grid';
 export * from './utilities/grid/GridItem';
 export * from './utilities/hooks/useBreakpoint/useBreakpoint';

package/dist/layouts/AppLayout/AppLayout.d.ts

@@ -129,8 +129,20 @@ export interface AppLayoutProps extends ComponentPropsWithoutRef<'div'> {
      * Additional props for the sidebar `<div>` element.
      */
     sidebarProps?: ComponentPropsWithoutRef<'div'>;
+    /**
+     * Distance from the top of the viewport to the top of the layout, used to
+     * size the layout height (`100dvh - topOffset`). Set this when you render
+     * chrome above the layout (e.g. a banner) whose height the layout must
+     * account for — pass the measured height reactively.
+     *
+     * A number is treated as pixels; a string is used as-is (e.g. '3rem').
+     * When provided, this value is used verbatim and the built-in auto-measure
+     * is disabled. When omitted, the layout measures its own offset from the
+     * document top and keeps it updated.
+     */
+    topOffset?: number | string;
 }
 /**
  * AppLayout UI component
  */
-export declare const AppLayout: ({ children, className, drawerContent, drawerProps, hasDrawerToggle, hasSidebarToggle, isDrawerOpen, isSidebarCollapsed, keyboardShortcuts, labels, mainBackground, mainContentElement, mainContentMaxWidth, mainContentProps, onDrawerToggle, onSidebarToggle, scrollableContent, sidebarBackground, sidebarCollapsedWidth, sidebarExpandedWidth, sidebarExpandedWidthMax, sidebarExpandedWidthMin, sidebarProps, ...props }: AppLayoutProps) => import("react/jsx-runtime").JSX.Element;
+export declare const AppLayout: ({ children, className, drawerContent, drawerProps, hasDrawerToggle, hasSidebarToggle, isDrawerOpen, isSidebarCollapsed, keyboardShortcuts, labels, mainBackground, mainContentElement, mainContentMaxWidth, mainContentProps, onDrawerToggle, onSidebarToggle, scrollableContent, sidebarBackground, sidebarCollapsedWidth, sidebarExpandedWidth, sidebarExpandedWidthMax, sidebarExpandedWidthMin, sidebarProps, topOffset, ...props }: AppLayoutProps) => import("react/jsx-runtime").JSX.Element;

package/dist/utilities/GlobalWrapper/GlobalWrapper.d.ts

@@ -1,4 +1,5 @@
 import { ReactNode } from 'react';
+import { ThemeContextProviderProps } from '../context-providers/ThemeContext/ThemeContext';
 /**
  * Prop types for GlobalWrapper
  */
@@ -7,15 +8,28 @@ interface GlobalWrapperProps {
      * Child components
      */
     children: ReactNode;
+    /**
+     * Opt in to color-mode theme switching. When `true`, children are wrapped in
+     * a `ThemeContextProvider` that owns the theme and drives the `data-theme`
+     * attribute on the document root. Defaults to `false` so apps that manage
+     * their own theme are unaffected. Configure via `themeProps`.
+     */
+    enableThemeSwitching?: boolean;
     /**
      * Maximum viewport width in pixels at which mobile nav mode is active.
      * Sets the `data-pds-mobile` attribute on `:root` for CSS to react to.
      * Defaults to 767 to align with `--pds-bp-s-only` (`max-width: 767px`).
      */
     mobileMaxWidth?: number;
+    /**
+     * Configuration forwarded to the `ThemeContextProvider` (for example,
+     * `defaultTheme`, `storageKey`, or controlled `theme`/`onThemeChange`).
+     * Only applied when `enableThemeSwitching` is `true`.
+     */
+    themeProps?: Omit<ThemeContextProviderProps, 'children'>;
 }
 /**
  * GlobalWrapper wrapper component.
  */
-export declare const GlobalWrapper: ({ children, mobileMaxWidth, }: GlobalWrapperProps) => import("react/jsx-runtime").JSX.Element;
+export declare const GlobalWrapper: ({ children, enableThemeSwitching, mobileMaxWidth, themeProps, }: GlobalWrapperProps) => import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/utilities/context-providers/ThemeContext/ThemeContext.d.ts

@@ -0,0 +1,113 @@
+import React, { ReactNode, RefObject } from 'react';
+/**
+ * The user's color-mode choice. Matches the ThemeSwitcher component's options.
+ * `'system'` follows the OS via `prefers-color-scheme`.
+ */
+export type Theme = 'light' | 'dark' | 'system';
+/**
+ * The concrete theme applied to the `data-theme` attribute. `'system'` is
+ * resolved to one of these before being applied.
+ */
+export type ResolvedTheme = 'light' | 'dark';
+interface ThemeContextValue {
+    /** Resolved theme applied to `data-theme` (`'system'` → `'light' | 'dark'`). */
+    resolvedTheme: ResolvedTheme;
+    /** Update the theme. In controlled mode this only notifies `onThemeChange`. */
+    setTheme: (theme: Theme) => void;
+    /** The user's current choice (`'system'` preserved as-is). */
+    theme: Theme;
+}
+export declare const ThemeContext: React.Context<ThemeContextValue>;
+/**
+ * Prop types for ThemeContextProvider
+ */
+export interface ThemeContextProviderProps {
+    /**
+     * Child components.
+     */
+    children: ReactNode;
+    /**
+     * Fallback theme when nothing is stored (and in uncontrolled mode).
+     * Defaults to `'light'`.
+     */
+    defaultTheme?: Theme;
+    /**
+     * Opt out of the inline anti-flash script the provider renders before its
+     * children. That script sets `data-theme` from `localStorage` during SSR
+     * before first paint, preventing a flash of the wrong theme. It is only
+     * rendered for the uncontrolled, persisted, whole-page case (no `nodeRef`);
+     * set this to `true` to suppress it — for example, if you inject the script
+     * yourself via {@link getThemeInitScript}. Defaults to `false`.
+     */
+    disableInitScript?: boolean;
+    /**
+     * Element to receive the `data-theme` attribute. Defaults to
+     * `document.documentElement` (the whole page). Provide a ref to scope theming
+     * to a subtree — for example, an embedded preview or a themed region.
+     */
+    nodeRef?: RefObject<HTMLElement | null>;
+    /**
+     * Callback fired whenever the user changes the theme. This is the hook point
+     * for persisting to a server/preference service later. Fires in both
+     * controlled and uncontrolled modes.
+     */
+    onThemeChange?: (theme: Theme) => void;
+    /**
+     * Whether to persist the theme to `localStorage`. Ignored in controlled
+     * mode (when `theme` is provided). Defaults to `true`.
+     */
+    persist?: boolean;
+    /**
+     * `localStorage` key used to persist the theme. Defaults to `'pds-theme'`.
+     */
+    storageKey?: string;
+    /**
+     * Controlled theme value. When provided, the consuming app owns the value
+     * (for example, sourced from a preference service) and the provider stops
+     * writing to `localStorage` — it only resolves and applies the value. Pair
+     * with `onThemeChange` to receive user-initiated changes.
+     */
+    theme?: Theme;
+}
+/**
+ * Options for {@link getThemeInitScript}. Match these to the values passed to
+ * the `ThemeContextProvider` (or `GlobalWrapper`'s `themeProps`).
+ */
+export interface ThemeInitScriptOptions {
+    /** Fallback theme when nothing is stored. Defaults to `'light'`. */
+    defaultTheme?: Theme;
+    /** `localStorage` key the provider persists to. Defaults to `'pds-theme'`. */
+    storageKey?: string;
+}
+/**
+ * Returns a tiny synchronous script (as a string) that sets the `data-theme`
+ * attribute on the document root from the persisted preference **before first
+ * paint** — preventing a flash of the wrong theme on server-rendered pages (a
+ * flash the provider alone cannot prevent, since it only applies the theme
+ * after hydration).
+ *
+ * The `ThemeContextProvider` renders this script automatically for the
+ * uncontrolled, persisted, whole-page case, so most apps never call this
+ * directly. It is exported for advanced setups that want to place the script
+ * themselves (for example, in the document `<head>`). Note: importing it drags
+ * in this client module, so it cannot be called from a React Server Component —
+ * let the provider inject it, or inline the string. Either way, add
+ * `suppressHydrationWarning` to the `<html>` element, since the script mutates
+ * it before React hydrates.
+ */
+export declare const getThemeInitScript: ({ defaultTheme, storageKey, }?: ThemeInitScriptOptions) => string;
+/**
+ * ThemeContextProvider — owns color-mode state and drives the `data-theme`
+ * attribute on the document root.
+ *
+ * Works standalone or via `GlobalWrapper`'s opt-in. Persists to `localStorage`
+ * by default, and exposes a controlled mode (`theme` + `onThemeChange`) so an
+ * application can take over persistence.
+ */
+export declare const ThemeContextProvider: ({ children, defaultTheme, disableInitScript, nodeRef, onThemeChange, persist, storageKey, theme: controlledTheme, }: ThemeContextProviderProps) => import("react/jsx-runtime").JSX.Element;
+/**
+ * Access the current theme, the resolved theme, and a setter. Returns a no-op
+ * default when no `ThemeContextProvider` is present.
+ */
+export declare const useTheme: () => ThemeContextValue;
+export {};

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@pantheon-systems/pds-toolkit-react",
 	"technology": "React",
-	"version": "2.0.0-alpha.44",
+	"version": "2.0.0-alpha.45",
 	"description": "PDS toolkit built using the React framework",
 	"publishConfig": {
 		"access": "public",
@@ -56,7 +56,7 @@
 		"build:css:packageExtraCss": "PDS_CSS_LAYER=pds-v2 node scripts/package-extra-css.js",
 		"build:css:watch": "npm run build:css -- -w",
 		"prestorybook": "node scripts/filter-exports-by-tags.js && npm run build:css && npm run build:css:components && npm run build:css:layouts && npm run generate:ux-writing-search-index && npm run generate:ux-writing-guide",
-		"storybook": "storybook dev -p 6006",
+		"storybook": "PDS_CSS_LAYER=pds-v2 storybook dev -p 6006",
 		"prebuild": "npm run build:css && npm run build:css:components && npm run build:css:layouts && npm run build:css:packageExtraCss && npm run generate:ux-writing-search-index && npm run generate:ux-writing-guide",
 		"build": "NODE_OPTIONS=--max-old-space-size=4096 NODE_ENV=production storybook build",
 		"build-storybook": "NODE_ENV=production storybook build",