@tempots/beatui 0.82.1 → 0.83.3

package/dist/types/tokens/typography.d.ts

@@ -1,52 +1,121 @@
+/**
+ * Typography design tokens for BeatUI.
+ *
+ * Defines the complete typographic scale including font sizes, weights, line heights,
+ * letter spacing, font families, and semantic font role mappings. All values are
+ * converted to CSS custom properties at build time.
+ *
+ * @module
+ */
+/**
+ * The base font size unit used as the foundation for the font size scale.
+ *
+ * @default '1rem'
+ */
+export declare const baseFontSize = "1rem";
+/**
+ * Font size scale mapping size names to `[fontSize, { lineHeight }]` tuples.
+ * Each entry provides a font size derived from `--base-font-size` via `calc()`
+ * and its recommended line height. When `--base-font-size` is `1rem` (default),
+ * computed values match the pixel sizes shown.
+ *
+ * | Name | Multiplier | Line Height      | Pixels (at 1rem base) |
+ * |------|------------|------------------|-----------------------|
+ * | 3xs  | 0.5        | base * 0.75      | 8px                   |
+ * | 2xs  | 0.625      | base * 0.75      | 10px                  |
+ * | xs   | 0.75       | base             | 12px                  |
+ * | sm   | 0.875      | base * 1.25      | 14px                  |
+ * | md   | 1          | base * 1.5       | 16px                  |
+ * | lg   | 1.125      | base * 1.75      | 18px                  |
+ * | xl   | 1.25       | base * 1.75      | 20px                  |
+ * | 2xl  | 1.5        | base * 2         | 24px                  |
+ * | ...  | ...        | ...              | ...                   |
+ * | 9xl  | 8          | 1 (unitless)     | 128px                 |
+ */
 export declare const fontSize: {
-    readonly '3xs': readonly ["0.5rem", {
-        readonly lineHeight: "0.75rem";
+    readonly '3xs': readonly ["calc(var(--base-font-size) * 0.5)", {
+        readonly lineHeight: "calc(var(--base-font-size) * 0.75)";
     }];
-    readonly '2xs': readonly ["0.625rem", {
-        readonly lineHeight: "0.75rem";
+    readonly '2xs': readonly ["calc(var(--base-font-size) * 0.625)", {
+        readonly lineHeight: "calc(var(--base-font-size) * 0.75)";
     }];
-    readonly xs: readonly ["0.75rem", {
-        readonly lineHeight: "1rem";
+    readonly xs: readonly ["calc(var(--base-font-size) * 0.75)", {
+        readonly lineHeight: "var(--base-font-size)";
     }];
-    readonly sm: readonly ["0.875rem", {
-        readonly lineHeight: "1.25rem";
+    readonly sm: readonly ["calc(var(--base-font-size) * 0.875)", {
+        readonly lineHeight: "calc(var(--base-font-size) * 1.25)";
     }];
-    readonly md: readonly ["1rem", {
-        readonly lineHeight: "1.5rem";
+    readonly md: readonly ["var(--base-font-size)", {
+        readonly lineHeight: "calc(var(--base-font-size) * 1.5)";
     }];
-    readonly lg: readonly ["1.125rem", {
-        readonly lineHeight: "1.75rem";
+    readonly lg: readonly ["calc(var(--base-font-size) * 1.125)", {
+        readonly lineHeight: "calc(var(--base-font-size) * 1.75)";
     }];
-    readonly xl: readonly ["1.25rem", {
-        readonly lineHeight: "1.75rem";
+    readonly xl: readonly ["calc(var(--base-font-size) * 1.25)", {
+        readonly lineHeight: "calc(var(--base-font-size) * 1.75)";
     }];
-    readonly '2xl': readonly ["1.5rem", {
-        readonly lineHeight: "2rem";
+    readonly '2xl': readonly ["calc(var(--base-font-size) * 1.5)", {
+        readonly lineHeight: "calc(var(--base-font-size) * 2)";
     }];
-    readonly '3xl': readonly ["1.875rem", {
-        readonly lineHeight: "2.25rem";
+    readonly '3xl': readonly ["calc(var(--base-font-size) * 1.875)", {
+        readonly lineHeight: "calc(var(--base-font-size) * 2.25)";
     }];
-    readonly '4xl': readonly ["2.25rem", {
-        readonly lineHeight: "2.5rem";
+    readonly '4xl': readonly ["calc(var(--base-font-size) * 2.25)", {
+        readonly lineHeight: "calc(var(--base-font-size) * 2.5)";
     }];
-    readonly '5xl': readonly ["3rem", {
+    readonly '5xl': readonly ["calc(var(--base-font-size) * 3)", {
         readonly lineHeight: "1";
     }];
-    readonly '6xl': readonly ["3.75rem", {
+    readonly '6xl': readonly ["calc(var(--base-font-size) * 3.75)", {
         readonly lineHeight: "1";
     }];
-    readonly '7xl': readonly ["4.5rem", {
+    readonly '7xl': readonly ["calc(var(--base-font-size) * 4.5)", {
         readonly lineHeight: "1";
     }];
-    readonly '8xl': readonly ["6rem", {
+    readonly '8xl': readonly ["calc(var(--base-font-size) * 6)", {
         readonly lineHeight: "1";
     }];
-    readonly '9xl': readonly ["8rem", {
+    readonly '9xl': readonly ["calc(var(--base-font-size) * 8)", {
         readonly lineHeight: "1";
     }];
 };
+/**
+ * Returns a font size that is a given number of steps away from the provided size
+ * in the font size scale. Positive steps move toward larger sizes; negative steps
+ * move toward smaller sizes. The result is clamped to the available range.
+ *
+ * @param size - The starting font size name
+ * @param steps - Number of steps to move (positive = larger, negative = smaller)
+ * @returns The resulting font size name
+ * @throws If the provided size is not a valid font size name
+ *
+ * @example
+ * ```ts
+ * changeFontSize('md', 1)  // 'lg'
+ * changeFontSize('md', -1) // 'sm'
+ * changeFontSize('9xl', 5) // '9xl' (clamped)
+ * ```
+ */
 export declare function changeFontSize(size: FontSize, steps: number): "sm" | "md" | "lg" | "xl" | "2xl" | "xs" | "3xl" | "4xl" | "2xs" | "3xs" | "5xl" | "6xl" | "7xl" | "8xl" | "9xl";
+/**
+ * Union type of all available font size names.
+ */
 export type FontSize = keyof typeof fontSize;
+/**
+ * Font weight scale mapping weight names to their numeric CSS values.
+ *
+ * | Name       | Value |
+ * |------------|-------|
+ * | thin       | 100   |
+ * | extralight | 200   |
+ * | light      | 300   |
+ * | normal     | 400   |
+ * | medium     | 500   |
+ * | semibold   | 600   |
+ * | bold       | 700   |
+ * | extrabold  | 800   |
+ * | black      | 900   |
+ */
 export declare const fontWeight: {
     readonly thin: "100";
     readonly extralight: "200";
@@ -58,7 +127,22 @@ export declare const fontWeight: {
     readonly extrabold: "800";
     readonly black: "900";
 };
+/**
+ * Union type of all available font weight names.
+ */
 export type FontWeight = keyof typeof fontWeight;
+/**
+ * Line height scale mapping names to unitless multiplier values.
+ *
+ * | Name    | Value |
+ * |---------|-------|
+ * | none    | 1     |
+ * | tight   | 1.25  |
+ * | snug    | 1.375 |
+ * | normal  | 1.5   |
+ * | relaxed | 1.625 |
+ * | loose   | 2     |
+ */
 export declare const lineHeight: {
     readonly none: "1";
     readonly tight: "1.25";
@@ -67,7 +151,22 @@ export declare const lineHeight: {
     readonly relaxed: "1.625";
     readonly loose: "2";
 };
+/**
+ * Union type of all available line height names.
+ */
 export type LineHeight = keyof typeof lineHeight;
+/**
+ * Letter spacing scale mapping names to `em`-based values.
+ *
+ * | Name    | Value    |
+ * |---------|----------|
+ * | tighter | -0.05em  |
+ * | tight   | -0.025em |
+ * | normal  | 0em      |
+ * | wide    | 0.025em  |
+ * | wider   | 0.05em   |
+ * | widest  | 0.1em    |
+ */
 export declare const letterSpacing: {
     readonly tighter: "-0.05em";
     readonly tight: "-0.025em";
@@ -76,29 +175,218 @@ export declare const letterSpacing: {
     readonly wider: "0.05em";
     readonly widest: "0.1em";
 };
+/**
+ * Union type of all available letter spacing names.
+ */
 export type LetterSpacing = keyof typeof letterSpacing;
+/**
+ * Font family stacks mapping family names to ordered arrays of font names.
+ * Each stack provides a comprehensive fallback chain including system fonts and emoji support.
+ */
 export declare const fontFamily: {
     readonly sans: readonly ["system-ui", "-apple-system", "BlinkMacSystemFont", "\"Segoe UI\"", "Roboto", "\"Helvetica Neue\"", "Arial", "\"Noto Sans\"", "sans-serif", "\"Apple Color Emoji\"", "\"Segoe UI Emoji\"", "\"Segoe UI Symbol\"", "\"Noto Color Emoji\""];
     readonly serif: readonly ["ui-serif", "Georgia", "Cambria", "\"Times New Roman\"", "Times", "serif"];
     readonly mono: readonly ["ui-monospace", "SFMono-Regular", "\"SF Mono\"", "Consolas", "\"Liberation Mono\"", "Menlo", "monospace"];
 };
+/**
+ * Union type of all available font family names.
+ */
 export type FontFamily = keyof typeof fontFamily;
+/**
+ * Partial record for overriding default font family stacks.
+ * Values can be a single font string or an array of font names.
+ *
+ * @example
+ * ```ts
+ * const overrides: FontFamilyOverrides = {
+ *   sans: ['Inter', 'system-ui', 'sans-serif'],
+ *   mono: '"Fira Code", monospace',
+ * }
+ * ```
+ */
 export type FontFamilyOverrides = Partial<Record<FontFamily, string | readonly string[]>>;
+/**
+ * Tuple of all semantic font role names.
+ */
 export declare const semanticFontNames: readonly ["body", "heading", "display", "mono", "ui", "prose"];
+/**
+ * Union type of all semantic font role names.
+ */
 export type SemanticFontName = (typeof semanticFontNames)[number];
+/**
+ * Partial record for overriding default semantic font family assignments.
+ *
+ * @example
+ * ```ts
+ * const overrides: SemanticFontOverrides = {
+ *   heading: 'var(--font-family-serif)',
+ * }
+ * ```
+ */
 export type SemanticFontOverrides = Partial<Record<SemanticFontName, string>>;
+/**
+ * Returns the CSS custom property name for a font size.
+ *
+ * @param size - The font size name
+ * @returns The CSS variable name (e.g., `'--font-size-md'`)
+ *
+ * @example
+ * ```ts
+ * getFontSizeVarName('md') // '--font-size-md'
+ * ```
+ */
 export declare function getFontSizeVarName(size: FontSize): string;
+/**
+ * Returns a CSS `var()` expression referencing the font size custom property.
+ *
+ * @param size - The font size name
+ * @returns A CSS `var()` string (e.g., `'var(--font-size-md)'`)
+ *
+ * @example
+ * ```ts
+ * getFontSizeVar('md') // 'var(--font-size-md)'
+ * ```
+ */
 export declare function getFontSizeVar(size: FontSize): string;
+/**
+ * Returns the CSS custom property name for the base font size.
+ *
+ * @returns The CSS variable name `'--base-font-size'`
+ */
+export declare function getBaseFontSizeVarName(): string;
+/**
+ * Returns a CSS `var()` expression referencing the base font size custom property.
+ *
+ * @returns A CSS `var()` string `'var(--base-font-size)'`
+ */
+export declare function getBaseFontSizeVar(): string;
+/**
+ * Returns the CSS custom property name for a font size's paired line height.
+ *
+ * @param size - The font size name
+ * @returns The CSS variable name (e.g., `'--font-size-md-lh'`)
+ */
+export declare function getFontSizeLineHeightVarName(size: FontSize): string;
+/**
+ * Returns a CSS `var()` expression referencing the font size line height custom property.
+ *
+ * @param size - The font size name
+ * @returns A CSS `var()` string (e.g., `'var(--font-size-md-lh)'`)
+ */
+export declare function getFontSizeLineHeightVar(size: FontSize): string;
+/**
+ * Returns the CSS custom property name for a font weight.
+ *
+ * @param weight - The font weight name
+ * @returns The CSS variable name (e.g., `'--font-weight-bold'`)
+ */
 export declare function getFontWeightVarName(weight: FontWeight): string;
+/**
+ * Returns a CSS `var()` expression referencing the font weight custom property.
+ *
+ * @param weight - The font weight name
+ * @returns A CSS `var()` string (e.g., `'var(--font-weight-bold)'`)
+ */
 export declare function getFontWeightVar(weight: FontWeight): string;
+/**
+ * Returns the CSS custom property name for a line height.
+ *
+ * @param height - The line height name
+ * @returns The CSS variable name (e.g., `'--line-height-normal'`)
+ */
 export declare function getLineHeightVarName(height: LineHeight): string;
+/**
+ * Returns a CSS `var()` expression referencing the line height custom property.
+ *
+ * @param height - The line height name
+ * @returns A CSS `var()` string (e.g., `'var(--line-height-normal)'`)
+ */
 export declare function getLineHeightVar(height: LineHeight): string;
+/**
+ * Returns the CSS custom property name for a letter spacing value.
+ *
+ * @param spacing - The letter spacing name
+ * @returns The CSS variable name (e.g., `'--letter-spacing-wide'`)
+ */
 export declare function getLetterSpacingVarName(spacing: LetterSpacing): string;
+/**
+ * Returns a CSS `var()` expression referencing the letter spacing custom property.
+ *
+ * @param spacing - The letter spacing name
+ * @returns A CSS `var()` string (e.g., `'var(--letter-spacing-wide)'`)
+ */
 export declare function getLetterSpacingVar(spacing: LetterSpacing): string;
+/**
+ * Returns the CSS custom property name for a font family.
+ *
+ * @param family - The font family name
+ * @returns The CSS variable name (e.g., `'--font-family-sans'`)
+ */
 export declare function getFontFamilyVarName(family: FontFamily): string;
+/**
+ * Returns a CSS `var()` expression referencing the font family custom property.
+ *
+ * @param family - The font family name
+ * @returns A CSS `var()` string (e.g., `'var(--font-family-sans)'`)
+ */
 export declare function getFontFamilyVar(family: FontFamily): string;
+/**
+ * Returns the CSS custom property name for a semantic font role.
+ *
+ * @param name - The semantic font name
+ * @returns The CSS variable name (e.g., `'--font-body'`)
+ */
 export declare function getSemanticFontVarName(name: SemanticFontName): string;
+/**
+ * Returns a CSS `var()` expression referencing the semantic font custom property.
+ *
+ * @param name - The semantic font name
+ * @returns A CSS `var()` string (e.g., `'var(--font-body)'`)
+ */
 export declare function getSemanticFontVar(name: SemanticFontName): string;
+/**
+ * Generates CSS custom property declarations for all typography tokens, including
+ * the base font size, font sizes, per-size line heights, font weights, semantic
+ * line heights, letter spacing, and font families.
+ *
+ * @returns A record mapping CSS variable names to their values
+ *
+ * @example
+ * ```ts
+ * const vars = generateTypographyVariables()
+ * // vars['--base-font-size'] === '1rem'
+ * // vars['--font-size-md'] === 'var(--base-font-size)'
+ * // vars['--font-size-md-lh'] === 'calc(var(--base-font-size) * 1.5)'
+ * // vars['--font-weight-bold'] === '700'
+ * ```
+ */
 export declare function generateTypographyVariables(): Record<string, string>;
+/**
+ * Generates CSS custom property declarations for font family overrides.
+ * Only produces variables for the families specified in the overrides.
+ *
+ * @param overrides - Optional font family overrides
+ * @returns A record mapping CSS variable names to their values, or an empty record if no overrides
+ *
+ * @example
+ * ```ts
+ * const vars = generateFontFamilyOverrideVariables({ sans: ['Inter', 'sans-serif'] })
+ * // vars['--font-family-sans'] === 'Inter, sans-serif'
+ * ```
+ */
 export declare function generateFontFamilyOverrideVariables(overrides?: FontFamilyOverrides): Record<string, string>;
+/**
+ * Generates CSS custom property declarations for semantic font roles and
+ * default font family aliases. Merges defaults with any provided overrides.
+ *
+ * @param overrides - Optional overrides for semantic font role assignments
+ * @returns A record mapping CSS variable names to their values
+ *
+ * @example
+ * ```ts
+ * const vars = generateSemanticFontVariables({ heading: 'var(--font-family-serif)' })
+ * // vars['--font-heading'] === 'var(--font-family-serif)'
+ * // vars['--default-font-family'] === 'var(--font-body)'
+ * ```
+ */
 export declare function generateSemanticFontVariables(overrides?: SemanticFontOverrides): Record<string, string>;

package/dist/types/tokens/z-index.d.ts

@@ -1,3 +1,29 @@
+/**
+ * Z-index design tokens for BeatUI.
+ *
+ * Defines a consistent layering system for stacking context management.
+ * Values increase in increments of 10 to allow intermediate values when needed.
+ * The scale covers common UI layers from base content through navigation,
+ * overlays, tooltips, and notifications.
+ *
+ * @module
+ */
+/**
+ * Z-index scale definitions mapping layer names to numeric values.
+ *
+ * | Name         | Value | Use case                |
+ * |--------------|-------|-------------------------|
+ * | base         | 0     | Default stacking        |
+ * | raised       | 10    | Slightly elevated items |
+ * | navigation   | 20    | Nav bars, headers       |
+ * | sidebar      | 20    | Side navigation         |
+ * | overlay      | 50    | Backdrop overlays       |
+ * | modal        | 60    | Modal dialogs           |
+ * | tooltip      | 70    | Tooltip content         |
+ * | popover      | 80    | Popover menus           |
+ * | notification | 90    | Toast notifications     |
+ * | maximum      | 100   | Highest priority        |
+ */
 export declare const zIndex: {
     readonly base: 0;
     readonly raised: 10;
@@ -10,7 +36,43 @@ export declare const zIndex: {
     readonly notification: 90;
     readonly maximum: 100;
 };
+/**
+ * Union type of all available z-index layer names.
+ */
 export type ZIndexName = keyof typeof zIndex;
+/**
+ * Returns the CSS custom property name for a z-index layer.
+ *
+ * @param level - The z-index layer name
+ * @returns The CSS variable name (e.g., `'--z-index-modal'`)
+ *
+ * @example
+ * ```ts
+ * getZIndexVarName('modal') // '--z-index-modal'
+ * ```
+ */
 export declare function getZIndexVarName(level: ZIndexName): string;
+/**
+ * Returns a CSS `var()` expression referencing the z-index custom property.
+ *
+ * @param level - The z-index layer name
+ * @returns A CSS `var()` string (e.g., `'var(--z-index-modal)'`)
+ *
+ * @example
+ * ```ts
+ * getZIndexVar('modal') // 'var(--z-index-modal)'
+ * ```
+ */
 export declare function getZIndexVar(level: ZIndexName): string;
+/**
+ * Generates CSS custom property declarations for all z-index tokens.
+ *
+ * @returns A record mapping CSS variable names to their numeric string values
+ *
+ * @example
+ * ```ts
+ * const vars = generateZIndexVariables()
+ * // vars['--z-index-modal'] === '60'
+ * ```
+ */
 export declare function generateZIndexVariables(): Record<string, string>;