@nationaldesignstudio/react 0.5.6 → 0.6.1

package/dist/index.d.ts

@@ -12,7 +12,7 @@ import { Select as Select$1 } from '@base-ui-components/react/select';
 import { Tooltip as Tooltip$1 } from '@base-ui-components/react/tooltip';
 import { Dialog as Dialog$1 } from '@base-ui-components/react/dialog';
 import { ClassValue } from 'clsx';
-import { CSSVariableMap, NestedStringRecord, ColorThemeName, SurfaceThemeName } from '@nds-design-system/tokens';
+import { CSSVariableMap, NestedStringRecord, ColorThemeName, SurfaceThemeName, ResolvedProjectTheme } from '@nds-design-system/tokens';
 
 declare const accordionVariants: tailwind_variants.TVReturnType<{
     colorScheme: {
@@ -3268,6 +3268,16 @@ declare const cardVariants: tailwind_variants.TVReturnType<{
          * Use with Background components for images/gradients.
          */
         overlay: string;
+        /**
+         * Profile layout - square image with stacked content below.
+         * Ideal for team member cards, user profiles, testimonials.
+         */
+        profile: string;
+        /**
+         * Compact layout - small thumbnail with condensed horizontal content.
+         * Ideal for news items, article previews, resource lists.
+         */
+        compact: string;
     };
 }, undefined, "relative flex overflow-hidden rounded-surface-card bg-card-background stroke-surface-card border-border-subtle border-solid", tailwind_variants_dist_config_js.TVConfig<{
     layout: {
@@ -3278,6 +3288,16 @@ declare const cardVariants: tailwind_variants.TVReturnType<{
          * Use with Background components for images/gradients.
          */
         overlay: string;
+        /**
+         * Profile layout - square image with stacked content below.
+         * Ideal for team member cards, user profiles, testimonials.
+         */
+        profile: string;
+        /**
+         * Compact layout - small thumbnail with condensed horizontal content.
+         * Ideal for news items, article previews, resource lists.
+         */
+        compact: string;
     };
 }, {
     layout: {
@@ -3288,6 +3308,16 @@ declare const cardVariants: tailwind_variants.TVReturnType<{
          * Use with Background components for images/gradients.
          */
         overlay: string;
+        /**
+         * Profile layout - square image with stacked content below.
+         * Ideal for team member cards, user profiles, testimonials.
+         */
+        profile: string;
+        /**
+         * Compact layout - small thumbnail with condensed horizontal content.
+         * Ideal for news items, article previews, resource lists.
+         */
+        compact: string;
     };
 }>, {
     layout: {
@@ -3298,6 +3328,16 @@ declare const cardVariants: tailwind_variants.TVReturnType<{
          * Use with Background components for images/gradients.
          */
         overlay: string;
+        /**
+         * Profile layout - square image with stacked content below.
+         * Ideal for team member cards, user profiles, testimonials.
+         */
+        profile: string;
+        /**
+         * Compact layout - small thumbnail with condensed horizontal content.
+         * Ideal for news items, article previews, resource lists.
+         */
+        compact: string;
     };
 }, undefined, tailwind_variants.TVReturnType<{
     layout: {
@@ -3308,6 +3348,16 @@ declare const cardVariants: tailwind_variants.TVReturnType<{
          * Use with Background components for images/gradients.
          */
         overlay: string;
+        /**
+         * Profile layout - square image with stacked content below.
+         * Ideal for team member cards, user profiles, testimonials.
+         */
+        profile: string;
+        /**
+         * Compact layout - small thumbnail with condensed horizontal content.
+         * Ideal for news items, article previews, resource lists.
+         */
+        compact: string;
     };
 }, undefined, "relative flex overflow-hidden rounded-surface-card bg-card-background stroke-surface-card border-border-subtle border-solid", tailwind_variants_dist_config_js.TVConfig<{
     layout: {
@@ -3318,6 +3368,16 @@ declare const cardVariants: tailwind_variants.TVReturnType<{
          * Use with Background components for images/gradients.
          */
         overlay: string;
+        /**
+         * Profile layout - square image with stacked content below.
+         * Ideal for team member cards, user profiles, testimonials.
+         */
+        profile: string;
+        /**
+         * Compact layout - small thumbnail with condensed horizontal content.
+         * Ideal for news items, article previews, resource lists.
+         */
+        compact: string;
     };
 }, {
     layout: {
@@ -3328,6 +3388,16 @@ declare const cardVariants: tailwind_variants.TVReturnType<{
          * Use with Background components for images/gradients.
          */
         overlay: string;
+        /**
+         * Profile layout - square image with stacked content below.
+         * Ideal for team member cards, user profiles, testimonials.
+         */
+        profile: string;
+        /**
+         * Compact layout - small thumbnail with condensed horizontal content.
+         * Ideal for news items, article previews, resource lists.
+         */
+        compact: string;
     };
 }>, unknown, unknown, undefined>>;
 interface CardProps extends React$1.HTMLAttributes<HTMLDivElement>, VariantProps<typeof cardVariants> {
@@ -3344,7 +3414,78 @@ interface CardProps extends React$1.HTMLAttributes<HTMLDivElement>, VariantProps
  * For overlay layout, use Background components for full-bleed backgrounds.
  */
 declare const Card: React$1.ForwardRefExoticComponent<CardProps & React$1.RefAttributes<HTMLDivElement>>;
-interface CardImageProps extends React$1.HTMLAttributes<HTMLDivElement> {
+declare const cardImageVariants: tailwind_variants.TVReturnType<{
+    layout: {
+        vertical: string;
+        horizontal: string;
+        overlay: string;
+        /** Profile: square aspect ratio for headshots/avatars */
+        profile: string;
+        /** Compact: fixed small size for thumbnails */
+        compact: string;
+    };
+}, undefined, "relative shrink-0 bg-bg-muted", tailwind_variants_dist_config_js.TVConfig<{
+    layout: {
+        vertical: string;
+        horizontal: string;
+        overlay: string;
+        /** Profile: square aspect ratio for headshots/avatars */
+        profile: string;
+        /** Compact: fixed small size for thumbnails */
+        compact: string;
+    };
+}, {
+    layout: {
+        vertical: string;
+        horizontal: string;
+        overlay: string;
+        /** Profile: square aspect ratio for headshots/avatars */
+        profile: string;
+        /** Compact: fixed small size for thumbnails */
+        compact: string;
+    };
+}>, {
+    layout: {
+        vertical: string;
+        horizontal: string;
+        overlay: string;
+        /** Profile: square aspect ratio for headshots/avatars */
+        profile: string;
+        /** Compact: fixed small size for thumbnails */
+        compact: string;
+    };
+}, undefined, tailwind_variants.TVReturnType<{
+    layout: {
+        vertical: string;
+        horizontal: string;
+        overlay: string;
+        /** Profile: square aspect ratio for headshots/avatars */
+        profile: string;
+        /** Compact: fixed small size for thumbnails */
+        compact: string;
+    };
+}, undefined, "relative shrink-0 bg-bg-muted", tailwind_variants_dist_config_js.TVConfig<{
+    layout: {
+        vertical: string;
+        horizontal: string;
+        overlay: string;
+        /** Profile: square aspect ratio for headshots/avatars */
+        profile: string;
+        /** Compact: fixed small size for thumbnails */
+        compact: string;
+    };
+}, {
+    layout: {
+        vertical: string;
+        horizontal: string;
+        overlay: string;
+        /** Profile: square aspect ratio for headshots/avatars */
+        profile: string;
+        /** Compact: fixed small size for thumbnails */
+        compact: string;
+    };
+}>, unknown, unknown, undefined>>;
+interface CardImageProps extends React$1.HTMLAttributes<HTMLDivElement>, VariantProps<typeof cardImageVariants> {
     /**
      * The image source URL
      */
@@ -3355,8 +3496,11 @@ interface CardImageProps extends React$1.HTMLAttributes<HTMLDivElement> {
     alt?: string;
 }
 /**
- * Card image area. For vertical layout, displays with 16:9 aspect ratio.
- * For horizontal layout, takes up ~40% width and stretches to content height.
+ * Card image area with layout-specific styling.
+ * - vertical: 16:9 aspect ratio, full width
+ * - horizontal: ~40% width, stretches to content height
+ * - profile: square aspect ratio for headshots/avatars
+ * - compact: fixed small size for thumbnails
  */
 declare const CardImage: React$1.ForwardRefExoticComponent<CardImageProps & React$1.RefAttributes<HTMLDivElement>>;
 declare const cardContentVariants: tailwind_variants.TVReturnType<{
@@ -4038,6 +4182,21 @@ declare const heroVariants: tailwind_variants.TVReturnType<{
             content: string[];
         };
     };
+    /**
+     * Vertical alignment of content within the hero.
+     * Provides a simpler API than variant for basic alignment needs.
+     */
+    contentAlign: {
+        top: {
+            content: string;
+        };
+        center: {
+            content: string;
+        };
+        bottom: {
+            content: string;
+        };
+    };
     colorScheme: {
         dark: {
             root: string;
@@ -4058,6 +4217,7 @@ declare const heroVariants: tailwind_variants.TVReturnType<{
     top: string;
     content: string[];
     title: string;
+    indicator: string;
 }, undefined, tailwind_variants_dist_config_js.TVConfig<{
     variant: {
         A1: {
@@ -4073,6 +4233,21 @@ declare const heroVariants: tailwind_variants.TVReturnType<{
             content: string[];
         };
     };
+    /**
+     * Vertical alignment of content within the hero.
+     * Provides a simpler API than variant for basic alignment needs.
+     */
+    contentAlign: {
+        top: {
+            content: string;
+        };
+        center: {
+            content: string;
+        };
+        bottom: {
+            content: string;
+        };
+    };
     colorScheme: {
         dark: {
             root: string;
@@ -4103,6 +4278,21 @@ declare const heroVariants: tailwind_variants.TVReturnType<{
             content: string[];
         };
     };
+    /**
+     * Vertical alignment of content within the hero.
+     * Provides a simpler API than variant for basic alignment needs.
+     */
+    contentAlign: {
+        top: {
+            content: string;
+        };
+        center: {
+            content: string;
+        };
+        bottom: {
+            content: string;
+        };
+    };
     colorScheme: {
         dark: {
             root: string;
@@ -4133,6 +4323,21 @@ declare const heroVariants: tailwind_variants.TVReturnType<{
             content: string[];
         };
     };
+    /**
+     * Vertical alignment of content within the hero.
+     * Provides a simpler API than variant for basic alignment needs.
+     */
+    contentAlign: {
+        top: {
+            content: string;
+        };
+        center: {
+            content: string;
+        };
+        bottom: {
+            content: string;
+        };
+    };
     colorScheme: {
         dark: {
             root: string;
@@ -4153,6 +4358,7 @@ declare const heroVariants: tailwind_variants.TVReturnType<{
     top: string;
     content: string[];
     title: string;
+    indicator: string;
 }, tailwind_variants.TVReturnType<{
     variant: {
         A1: {
@@ -4168,6 +4374,21 @@ declare const heroVariants: tailwind_variants.TVReturnType<{
             content: string[];
         };
     };
+    /**
+     * Vertical alignment of content within the hero.
+     * Provides a simpler API than variant for basic alignment needs.
+     */
+    contentAlign: {
+        top: {
+            content: string;
+        };
+        center: {
+            content: string;
+        };
+        bottom: {
+            content: string;
+        };
+    };
     colorScheme: {
         dark: {
             root: string;
@@ -4188,6 +4409,7 @@ declare const heroVariants: tailwind_variants.TVReturnType<{
     top: string;
     content: string[];
     title: string;
+    indicator: string;
 }, undefined, tailwind_variants_dist_config_js.TVConfig<{
     variant: {
         A1: {
@@ -4203,6 +4425,21 @@ declare const heroVariants: tailwind_variants.TVReturnType<{
             content: string[];
         };
     };
+    /**
+     * Vertical alignment of content within the hero.
+     * Provides a simpler API than variant for basic alignment needs.
+     */
+    contentAlign: {
+        top: {
+            content: string;
+        };
+        center: {
+            content: string;
+        };
+        bottom: {
+            content: string;
+        };
+    };
     colorScheme: {
         dark: {
             root: string;
@@ -4233,6 +4470,21 @@ declare const heroVariants: tailwind_variants.TVReturnType<{
             content: string[];
         };
     };
+    /**
+     * Vertical alignment of content within the hero.
+     * Provides a simpler API than variant for basic alignment needs.
+     */
+    contentAlign: {
+        top: {
+            content: string;
+        };
+        center: {
+            content: string;
+        };
+        bottom: {
+            content: string;
+        };
+    };
     colorScheme: {
         dark: {
             root: string;
@@ -4288,6 +4540,17 @@ interface HeroProps extends Omit<React$1.HTMLAttributes<HTMLElement>, "title">,
      * Use for USGovBanner, Navigation, etc.
      */
     top?: React$1.ReactNode;
+    /**
+     * Indicator slot for scroll hints, arrows, or other visual cues.
+     * Rendered at the bottom of the hero, below the main content.
+     * @example
+     * ```tsx
+     * <Hero indicator={<ChevronDown className="animate-bounce" />}>
+     *   <h1>Welcome</h1>
+     * </Hero>
+     * ```
+     */
+    indicator?: React$1.ReactNode;
     /**
      * Background for the hero. Can be:
      * - A color string (hex, rgb, etc.) for solid backgrounds
@@ -4954,6 +5217,11 @@ interface ThemeProviderProps {
     color?: ColorThemeName;
     /** Surface theme name (defaults to "base") */
     surface?: SurfaceThemeName;
+    /**
+     * Custom project theme created with defineTheme()
+     * When provided, overrides color/surface props with custom theme tokens
+     */
+    customTheme?: ResolvedProjectTheme;
     /** Children to render */
     children: ReactNode;
     /** Optional className for the wrapper div */
@@ -4978,13 +5246,28 @@ interface ThemeProviderProps {
  *   <App />
  * </ThemeProvider>
  *
- * // Mix and match
- * <ThemeProvider color="institution" surface="soft">
+ * // Use a custom project theme
+ * import { defineTheme, srgb } from "@nds-design-system/tokens";
+ *
+ * const myTheme = defineTheme({
+ *   name: "my-project",
+ *   extends: "base",
+ *   tokens: {
+ *     semantic: {
+ *       color: {
+ *         bg: { page: srgb("#FEFDF9") },
+ *         accent: { brand: srgb("#A68B5E") },
+ *       },
+ *     },
+ *   },
+ * });
+ *
+ * <ThemeProvider customTheme={myTheme}>
  *   <App />
  * </ThemeProvider>
  * ```
  */
-declare function ThemeProvider({ color, surface, children, className, applyStyles, }: ThemeProviderProps): react_jsx_runtime.JSX.Element;
+declare function ThemeProvider({ color, surface, customTheme, children, className, applyStyles, }: ThemeProviderProps): react_jsx_runtime.JSX.Element;
 
 /**
  * Theme Hooks

package/dist/index.js

@@ -3798,7 +3798,17 @@ var cardVariants = tv({
        * Overlay layout - content sits on top of full-bleed background.
        * Use with Background components for images/gradients.
        */
-      overlay: "w-full flex-col"
+      overlay: "w-full flex-col",
+      /**
+       * Profile layout - square image with stacked content below.
+       * Ideal for team member cards, user profiles, testimonials.
+       */
+      profile: "w-full flex-col",
+      /**
+       * Compact layout - small thumbnail with condensed horizontal content.
+       * Ideal for news items, article previews, resource lists.
+       */
+      compact: "w-full flex-row items-center gap-16"
     }
   },
   defaultVariants: {
@@ -3819,21 +3829,29 @@ var Card = React14.forwardRef(
 );
 Card.displayName = "Card";
 var cardImageVariants = tv({
-  base: [
-    "relative shrink-0 bg-bg-muted",
-    // Vertical: full width with aspect ratio
-    "aspect-video w-full",
-    // When in horizontal card (parent has flex-row), override
-    "[.flex-row>&]:aspect-auto [.flex-row>&]:w-2/5 [.flex-row>&]:self-stretch"
-  ]
+  base: "relative shrink-0 bg-bg-muted",
+  variants: {
+    layout: {
+      vertical: "aspect-video w-full",
+      horizontal: "aspect-auto w-2/5 self-stretch",
+      overlay: "aspect-video w-full",
+      /** Profile: square aspect ratio for headshots/avatars */
+      profile: "aspect-square w-full",
+      /** Compact: fixed small size for thumbnails */
+      compact: "size-80 rounded-8"
+    }
+  },
+  defaultVariants: {
+    layout: "vertical"
+  }
 });
 var CardImage = React14.forwardRef(
-  ({ className, src, alt = "", ...props }, ref) => {
+  ({ className, src, alt = "", layout, ...props }, ref) => {
     return /* @__PURE__ */ jsx(
       "div",
       {
         ref,
-        className: cardImageVariants({ class: className }),
+        className: cardImageVariants({ layout, class: className }),
         ...props,
         children: src && /* @__PURE__ */ jsx(
           "img",
@@ -3953,6 +3971,33 @@ var CardActions = React14.forwardRef(
   }
 );
 CardActions.displayName = "CardActions";
+var cardLinkVariants = tv({
+  base: "group/link flex items-center gap-4 text-text-muted transition-colors duration-200 hover:text-text-primary"
+});
+var CardLink = React14.forwardRef(
+  ({ className, children, showArrow = true, ...props }, ref) => {
+    return /* @__PURE__ */ jsxs(
+      "span",
+      {
+        ref,
+        className: cardLinkVariants({ class: className }),
+        ...props,
+        children: [
+          /* @__PURE__ */ jsx("span", { children }),
+          showArrow && /* @__PURE__ */ jsx(
+            "span",
+            {
+              "aria-hidden": "true",
+              className: "inline-block transition-transform duration-200 ease-out group-hover/link:translate-x-4",
+              children: "\u2192"
+            }
+          )
+        ]
+      }
+    );
+  }
+);
+CardLink.displayName = "CardLink";
 var NavbarContext = React14.createContext({
   isMobileMenuOpen: false,
   setIsMobileMenuOpen: () => {
@@ -4533,7 +4578,8 @@ var heroVariants = tv({
       "p-20",
       "md:p-56"
     ],
-    title: DEFAULT_TITLE_TYPOGRAPHY
+    title: DEFAULT_TITLE_TYPOGRAPHY,
+    indicator: "absolute inset-x-0 bottom-0 z-10 flex justify-center pb-24"
   },
   variants: {
     variant: {
@@ -4550,6 +4596,21 @@ var heroVariants = tv({
         content: ["items-center justify-center", "lg:p-64"]
       }
     },
+    /**
+     * Vertical alignment of content within the hero.
+     * Provides a simpler API than variant for basic alignment needs.
+     */
+    contentAlign: {
+      top: {
+        content: "justify-start"
+      },
+      center: {
+        content: "items-center justify-center"
+      },
+      bottom: {
+        content: "justify-end"
+      }
+    },
     colorScheme: {
       dark: {
         root: "bg-bg-page",
@@ -4614,7 +4675,9 @@ var Hero = React14.forwardRef(
     title,
     titleClassName,
     colorScheme = "dark",
+    contentAlign,
     top,
+    indicator,
     variant,
     background,
     overlayOpacity = 0,
@@ -4628,6 +4691,7 @@ var Hero = React14.forwardRef(
     const hasMediaBackground = background && !isColor;
     const styles = heroVariants({
       variant,
+      contentAlign,
       colorScheme,
       hasBackground: !!background
     });
@@ -4659,7 +4723,8 @@ var Hero = React14.forwardRef(
           /* @__PURE__ */ jsxs("div", { className: styles.content(), children: [
             title && /* @__PURE__ */ jsx("h1", { className: styles.title({ class: titleClassName }), children: title }),
             children
-          ] })
+          ] }),
+          indicator && /* @__PURE__ */ jsx("div", { className: styles.indicator(), children: indicator })
         ]
       }
     );
@@ -9184,6 +9249,7 @@ function deepMerge2(target, source) {
 function ThemeProvider({
   color = "base",
   surface = "base",
+  customTheme,
   children,
   className,
   applyStyles = true
@@ -9191,8 +9257,9 @@ function ThemeProvider({
   const { tokens: tokens2, cssVars } = useMemo(() => {
     const flatTokens = {};
     const baseColorModule = colorThemes.base;
-    const colorModule = colorThemes[color];
-    const mergedColor = color === "base" ? baseColorModule : mergeTokenModules(baseColorModule, colorModule);
+    const effectiveColor = customTheme ? customTheme.extends : color;
+    const colorModule = colorThemes[effectiveColor] ?? colorThemes.base;
+    const mergedColor = effectiveColor === "base" ? baseColorModule : mergeTokenModules(baseColorModule, colorModule);
     const colorTokens = mergedColor?.semantic?.color ?? mergedColor;
     Object.assign(flatTokens, processColorTokens(colorTokens));
     const baseSurfaceModule = surfaceThemes.base;
@@ -9201,13 +9268,24 @@ function ThemeProvider({
     const surfaceTokens = mergedSurface?.semantic?.surface ?? mergedSurface;
     Object.assign(flatTokens, processSurfaceTokens(surfaceTokens));
     const nestedTokens = flatToNested(flatTokens);
-    const cssVariables = flatToCSSVars(flatTokens);
+    let cssVariables = flatToCSSVars(flatTokens);
+    if (customTheme) {
+      cssVariables = {
+        ...cssVariables,
+        ...Object.fromEntries(
+          Object.entries(customTheme.cssVars).map(([key, value]) => [
+            key.startsWith("--") ? key : `--${key}`,
+            value
+          ])
+        )
+      };
+    }
     return { tokens: nestedTokens, cssVars: cssVariables };
-  }, [color, surface]);
+  }, [color, surface, customTheme]);
   const contextValue = {
     cssVars,
     tokens: tokens2,
-    colorTheme: color,
+    colorTheme: customTheme ? customTheme.extends : color,
     surfaceTheme: surface
   };
   return /* @__PURE__ */ jsx(ThemeContext.Provider, { value: contextValue, children: applyStyles ? /* @__PURE__ */ jsx("div", { style: cssVars, className, children }) : children });