@nationaldesignstudio/react 0.0.10 → 0.0.12

package/dist/lib/theme.d.ts

@@ -0,0 +1,330 @@
+/**
+ * Component-level theming interface
+ *
+ * This interface defines all the customizable design tokens that can be
+ * overridden at the component level. Components accepting a `theme` prop
+ * will apply these values as CSS custom properties, allowing fine-grained
+ * control over appearance without creating new variants.
+ *
+ * All values use primitive token names (e.g., "gray-100", "spacing-40")
+ * which are converted to CSS variable references internally.
+ */
+/**
+ * Color token names - maps to `--color-{name}` CSS variables
+ * @example "gray-100", "ember-v300", "alpha-black-10"
+ */
+export type ColorToken = "gray-50" | "gray-100" | "gray-200" | "gray-300" | "gray-400" | "gray-500" | "gray-600" | "gray-700" | "gray-800" | "gray-900" | "gray-1000" | "gray-1100" | "gray-1200" | "steel-50" | "steel-100" | "steel-200" | "steel-300" | "steel-400" | "steel-500" | "steel-600" | "steel-700" | "steel-800" | "steel-900" | "steel-1000" | "steel-1100" | "steel-1200" | "brown-50" | "brown-100" | "brown-200" | "brown-300" | "brown-400" | "brown-500" | "brown-600" | "brown-700" | "brown-800" | "brown-900" | "brown-1000" | "brown-1100" | "brown-1200" | "ember-50" | "ember-100" | "ember-200" | "ember-300" | "ember-400" | "ember-500" | "ember-600" | "ember-700" | "ember-800" | "ember-900" | "ember-v100" | "ember-v200" | "ember-v300" | "ember-v400" | "orange-50" | "orange-100" | "orange-200" | "orange-300" | "orange-400" | "orange-500" | "orange-600" | "orange-700" | "orange-800" | "orange-900" | "orange-v100" | "orange-v200" | "orange-v300" | "orange-v400" | "amber-50" | "amber-100" | "amber-200" | "amber-300" | "amber-400" | "amber-500" | "amber-600" | "amber-700" | "amber-800" | "amber-900" | "amber-v100" | "amber-v200" | "amber-v300" | "amber-v400" | "yellow-50" | "yellow-100" | "yellow-200" | "yellow-300" | "yellow-400" | "yellow-500" | "yellow-600" | "yellow-700" | "yellow-800" | "yellow-900" | "yellow-v100" | "yellow-v200" | "yellow-v300" | "yellow-v400" | "lime-50" | "lime-100" | "lime-200" | "lime-300" | "lime-400" | "lime-500" | "lime-600" | "lime-700" | "lime-800" | "lime-900" | "lime-v100" | "lime-v200" | "lime-v300" | "lime-v400" | "green-50" | "green-100" | "green-200" | "green-300" | "green-400" | "green-500" | "green-600" | "green-700" | "green-800" | "green-900" | "green-v100" | "green-v200" | "green-v300" | "green-v400" | "sage-50" | "sage-100" | "sage-200" | "sage-300" | "sage-400" | "sage-500" | "sage-600" | "sage-700" | "sage-800" | "sage-900" | "sage-v100" | "sage-v200" | "sage-v300" | "sage-v400" | "teal-50" | "teal-100" | "teal-200" | "teal-300" | "teal-400" | "teal-500" | "teal-600" | "teal-700" | "teal-800" | "teal-900" | "teal-v100" | "teal-v200" | "teal-v300" | "teal-v400" | "cyan-50" | "cyan-100" | "cyan-200" | "cyan-300" | "cyan-400" | "cyan-500" | "cyan-600" | "cyan-700" | "cyan-800" | "cyan-900" | "cyan-v100" | "cyan-v200" | "cyan-v300" | "cyan-v400" | "ice-50" | "ice-100" | "ice-200" | "ice-300" | "ice-400" | "ice-500" | "ice-600" | "ice-700" | "ice-800" | "ice-900" | "ice-v100" | "ice-v200" | "ice-v300" | "ice-v400" | "blue-50" | "blue-100" | "blue-200" | "blue-300" | "blue-400" | "blue-500" | "blue-600" | "blue-700" | "blue-800" | "blue-900" | "blue-v100" | "blue-v200" | "blue-v300" | "blue-v400" | "indigo-50" | "indigo-100" | "indigo-200" | "indigo-300" | "indigo-400" | "indigo-500" | "indigo-600" | "indigo-700" | "indigo-800" | "indigo-900" | "indigo-v100" | "indigo-v200" | "indigo-v300" | "indigo-v400" | "iris-50" | "iris-100" | "iris-200" | "iris-300" | "iris-400" | "iris-500" | "iris-600" | "iris-700" | "iris-800" | "iris-900" | "iris-v100" | "iris-v200" | "iris-v300" | "iris-v400" | "purple-50" | "purple-100" | "purple-200" | "purple-300" | "purple-400" | "purple-500" | "purple-600" | "purple-700" | "purple-800" | "purple-900" | "purple-v100" | "purple-v200" | "purple-v300" | "purple-v400" | "pink-50" | "pink-100" | "pink-200" | "pink-300" | "pink-400" | "pink-500" | "pink-600" | "pink-700" | "pink-800" | "pink-900" | "pink-v100" | "pink-v200" | "pink-v300" | "pink-v400" | "red-50" | "red-100" | "red-200" | "red-300" | "red-400" | "red-500" | "red-600" | "red-700" | "red-800" | "red-900" | "red-v100" | "red-v200" | "red-v300" | "red-v400" | "alpha-black-5" | "alpha-black-10" | "alpha-black-20" | "alpha-black-30" | "alpha-black-40" | "alpha-black-50" | "alpha-black-60" | "alpha-black-70" | "alpha-black-80" | "alpha-black-90" | "alpha-black-95" | "alpha-white-5" | "alpha-white-10" | "alpha-white-20" | "alpha-white-30" | "alpha-white-40" | "alpha-white-50" | "alpha-white-60" | "alpha-white-70" | "alpha-white-80" | "alpha-white-90" | "alpha-white-95" | "white" | "black";
+/**
+ * Spacing token names - maps to `--spacing-{name}` CSS variables
+ * @example "spacing-40", "spacing-72"
+ */
+export type SpacingToken = "spacing-0" | "spacing-2" | "spacing-4" | "spacing-6" | "spacing-8" | "spacing-10" | "spacing-11" | "spacing-12" | "spacing-16" | "spacing-20" | "spacing-24" | "spacing-28" | "spacing-32" | "spacing-36" | "spacing-40" | "spacing-48" | "spacing-56" | "spacing-64" | "spacing-72" | "spacing-80" | "spacing-96" | "spacing-112" | "spacing-128" | "spacing-144" | "spacing-160" | "spacing-176" | "spacing-192" | "spacing-208" | "spacing-224" | "spacing-240" | "spacing-256" | "spacing-288" | "spacing-320" | "spacing-352" | "spacing-384" | "spacing-400";
+/**
+ * Radius token names - maps to `--radii-{name}` CSS variables
+ * @example "radii-4", "radii-6"
+ */
+export type RadiusToken = "radii-0" | "radii-2" | "radii-4" | "radii-6" | "radii-8" | "radii-10" | "radii-11" | "radii-12" | "radii-16" | "radii-20" | "radii-24" | "radii-28" | "radii-32" | "radii-36" | "radii-40" | "radii-48" | "radii-56" | "radii-64" | "radii-72" | "radii-80" | "radii-96" | "radii-112" | "radii-128" | "radii-144" | "radii-160" | "radii-176" | "radii-192" | "radii-208" | "radii-224" | "radii-240" | "radii-256" | "radii-288" | "radii-320" | "radii-352" | "radii-384" | "radii-400";
+/**
+ * Font size token values - primitive font sizes available in the design system
+ * These correspond to Tailwind classes like `text-64`, `text-128`, etc.
+ * @example 64, 128, 192
+ */
+export type FontSizeToken = 9 | 11 | 12 | 14 | 16 | 18 | 21 | 24 | 28 | 32 | 36 | 42 | 48 | 56 | 64 | 72 | 84 | 88 | 96 | 112 | 128 | 148 | 168 | 192 | 224 | 256 | 280;
+/**
+ * Array of all available font sizes for use in UI selectors/dropdowns
+ */
+export declare const FONT_SIZES: FontSizeToken[];
+/**
+ * Helper to generate typography class string from font size
+ * @example fontSizeToClass(128) => "text-128 leading-128 tracking-128"
+ */
+export declare function fontSizeToClass(size: FontSizeToken): string;
+/**
+ * Helper to generate responsive typography class string
+ * @example responsiveTypographyClass(64, 128, 192) => "text-64 leading-64 tracking-64 md:text-128 md:leading-128 md:tracking-128 xl:text-192 xl:leading-192 xl:tracking-192"
+ */
+export declare function responsiveTypographyClass(mobile: FontSizeToken, tablet: FontSizeToken, desktop: FontSizeToken): string;
+export interface ComponentThemeColors {
+    /**
+     * Background color for sections
+     * @example "gray-100"
+     */
+    bgSection?: ColorToken;
+    /**
+     * Background color for cards
+     * @example "white"
+     */
+    cardBackground?: ColorToken;
+    /**
+     * Muted background color
+     * @example "gray-50"
+     */
+    bgMuted?: ColorToken;
+    /**
+     * Primary text color
+     * @example "gray-1100"
+     */
+    textPrimary?: ColorToken;
+    /**
+     * Secondary text color
+     * @example "gray-800"
+     */
+    textSecondary?: ColorToken;
+    /**
+     * Muted text color
+     * @example "gray-600"
+     */
+    textMuted?: ColorToken;
+    /**
+     * Inverted text color (for dark backgrounds)
+     * @example "gray-100"
+     */
+    textInverted?: ColorToken;
+    /**
+     * Link text color
+     * @example "gray-1100"
+     */
+    textLink?: ColorToken;
+    /**
+     * Link hover text color
+     * @example "gray-700"
+     */
+    textLinkHover?: ColorToken;
+    /**
+     * Brand accent color
+     * @example "ember-v300"
+     */
+    accentBrand?: ColorToken;
+    /**
+     * Soft brand accent color
+     * @example "ember-100"
+     */
+    accentBrandSoft?: ColorToken;
+    /**
+     * Subtle border color
+     * @example "alpha-black-10"
+     */
+    borderSubtle?: ColorToken;
+    /**
+     * Strong border color
+     * @example "alpha-black-20"
+     */
+    borderStrong?: ColorToken;
+    /**
+     * Focus border color (uses accentBrand by default)
+     * @example "ember-v300"
+     */
+    borderFocus?: ColorToken;
+    /**
+     * Divider border color
+     * @example "alpha-black-10"
+     */
+    borderDivider?: ColorToken;
+    /**
+     * Primary button background color
+     * @example "gray-1100"
+     */
+    buttonPrimaryBg?: ColorToken;
+    /**
+     * Primary button hover background color
+     * @example "gray-600"
+     */
+    buttonPrimaryBgHover?: ColorToken;
+    /**
+     * Secondary button background color
+     * @example "white"
+     */
+    buttonSecondaryBg?: ColorToken;
+    /**
+     * Secondary button hover background color
+     * @example "gray-100"
+     */
+    buttonSecondaryBgHover?: ColorToken;
+}
+export interface ComponentThemeSpatial {
+    /**
+     * Grid margin for large breakpoint
+     * @example "spacing-72"
+     */
+    gridLargeMargin?: SpacingToken;
+    /**
+     * Grid gutter for large breakpoint
+     * @example "spacing-24"
+     */
+    gridLargeGutter?: SpacingToken;
+    /**
+     * Number of grid columns for large breakpoint
+     */
+    gridLargeColumns?: number;
+    /**
+     * Grid margin for medium breakpoint
+     * @example "spacing-56"
+     */
+    gridMediumMargin?: SpacingToken;
+    /**
+     * Grid gutter for medium breakpoint
+     * @example "spacing-20"
+     */
+    gridMediumGutter?: SpacingToken;
+    /**
+     * Number of grid columns for medium breakpoint
+     */
+    gridMediumColumns?: number;
+    /**
+     * Grid margin for small breakpoint
+     * @example "spacing-24"
+     */
+    gridSmallMargin?: SpacingToken;
+    /**
+     * Grid gutter for small breakpoint
+     * @example "spacing-12"
+     */
+    gridSmallGutter?: SpacingToken;
+    /**
+     * Number of grid columns for small breakpoint
+     */
+    gridSmallColumns?: number;
+    /**
+     * Section gap for large breakpoint
+     * @example "spacing-64"
+     */
+    sectionLargeGap?: SpacingToken;
+    /**
+     * Section padding for large breakpoint
+     * @example "spacing-128"
+     */
+    sectionLargePadding?: SpacingToken;
+    /**
+     * Section gap for medium breakpoint
+     * @example "spacing-56"
+     */
+    sectionMediumGap?: SpacingToken;
+    /**
+     * Section padding for medium breakpoint
+     * @example "spacing-96"
+     */
+    sectionMediumPadding?: SpacingToken;
+    /**
+     * Section gap for small breakpoint
+     * @example "spacing-32"
+     */
+    sectionSmallGap?: SpacingToken;
+    /**
+     * Section padding for small breakpoint
+     * @example "spacing-64"
+     */
+    sectionSmallPadding?: SpacingToken;
+    /**
+     * Card gap for large size
+     * @example "spacing-10"
+     */
+    cardLargeGap?: SpacingToken;
+    /**
+     * Card padding for large size
+     * @example "spacing-24"
+     */
+    cardLargePadding?: SpacingToken;
+    /**
+     * Card gap for small size
+     * @example "spacing-12"
+     */
+    cardSmallGap?: SpacingToken;
+    /**
+     * Card padding for small size
+     * @example "spacing-16"
+     */
+    cardSmallPadding?: SpacingToken;
+}
+export interface ComponentThemeSurface {
+    /**
+     * Card border radius
+     * @example "radii-4"
+     */
+    cardRadius?: RadiusToken;
+    /**
+     * Card stroke/border width in pixels
+     * @example 1
+     */
+    cardStroke?: number;
+    /**
+     * Button border radius
+     * @example "radii-6"
+     */
+    buttonRadius?: RadiusToken;
+    /**
+     * Button stroke/border weight in pixels
+     * @example 1
+     */
+    buttonStrokeWeight?: number;
+}
+/**
+ * Complete component theme interface combining colors, spatial, and surface tokens.
+ *
+ * @example
+ * ```tsx
+ * const customTheme: ComponentTheme = {
+ *   colors: {
+ *     textPrimary: "gray-100",
+ *     accentBrand: "ember-500",
+ *   },
+ *   spatial: {
+ *     sectionLargePadding: "spacing-96",
+ *   },
+ *   surface: {
+ *     cardRadius: "radii-8",
+ *   },
+ * };
+ *
+ * <Tout theme={customTheme} ... />
+ * ```
+ */
+export interface ComponentTheme {
+    colors?: ComponentThemeColors;
+    spatial?: ComponentThemeSpatial;
+    surface?: ComponentThemeSurface;
+}
+/**
+ * Button-specific theme interface for customizing individual button appearance.
+ *
+ * @example
+ * ```tsx
+ * const buttonTheme: ButtonTheme = {
+ *   bg: "ember-500",
+ *   bgHover: "ember-600",
+ *   text: "white",
+ *   radius: "radii-8",
+ * };
+ *
+ * <Button theme={buttonTheme}>Themed Button</Button>
+ * ```
+ */
+export interface ButtonTheme {
+    /** Background color */
+    bg?: ColorToken;
+    /** Background color on hover */
+    bgHover?: ColorToken;
+    /** Background color on active/press */
+    bgActive?: ColorToken;
+    /** Text color */
+    text?: ColorToken;
+    /** Border color (if using border) */
+    borderColor?: ColorToken;
+    /** Border width in pixels (0 for no border) */
+    borderWidth?: number;
+    /** Border radius */
+    radius?: RadiusToken;
+}
+/**
+ * Converts a ComponentTheme object to CSS custom properties (inline style object)
+ *
+ * @param theme - The theme object to convert
+ * @returns An object suitable for use as React inline styles
+ */
+export declare function themeToStyleVars(theme: ComponentTheme | undefined): React.CSSProperties;
+/**
+ * Converts a ButtonTheme object to CSS custom properties (inline style object)
+ *
+ * @param theme - The button theme object to convert
+ * @returns An object suitable for use as React inline styles
+ */
+export declare function buttonThemeToStyleVars(theme: ButtonTheme | undefined): React.CSSProperties;