@tempots/beatui 0.82.0 → 0.83.0

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

@@ -1,25 +1,164 @@
+/**
+ * Motion (animation) design tokens for BeatUI.
+ *
+ * Defines animation duration and easing curve values that are exposed as CSS
+ * custom properties. Includes both primitive duration/easing tokens and semantic
+ * motion roles for transitions and animations throughout the UI.
+ *
+ * @module
+ */
+/**
+ * The base motion duration used as the foundation for the duration scale.
+ *
+ * @default '200ms'
+ */
+export declare const baseMotionDuration = "200ms";
+/**
+ * Motion duration scale mapping names to CSS time values.
+ * All values (except `instant`) are derived from `--motion-duration-base`
+ * via `calc()`, allowing the entire timing scale to be adjusted by changing
+ * a single variable.
+ *
+ * | Name    | Multiplier | Default |
+ * |---------|------------|---------|
+ * | instant | —          | 0s      |
+ * | fast    | 0.6        | 120ms   |
+ * | base    | 1          | 200ms   |
+ * | slow    | 1.6        | 320ms   |
+ * | relaxed | 2.4        | 480ms   |
+ */
 export declare const motionDurations: {
     readonly instant: "0s";
-    readonly fast: "120ms";
+    readonly fast: "calc(var(--motion-duration-base) * 0.6)";
     readonly base: "200ms";
-    readonly slow: "320ms";
-    readonly relaxed: "480ms";
+    readonly slow: "calc(var(--motion-duration-base) * 1.6)";
+    readonly relaxed: "calc(var(--motion-duration-base) * 2.4)";
 };
+/**
+ * Motion easing curve definitions mapping names to CSS `cubic-bezier()` values.
+ *
+ * | Name       | Curve                          | Use case                |
+ * |------------|--------------------------------|-------------------------|
+ * | standard   | cubic-bezier(0.2, 0, 0, 1)    | General transitions     |
+ * | emphasized | cubic-bezier(0.33, 1, 0.68, 1) | Attention-drawing motion |
+ * | entrance   | cubic-bezier(0, 0, 0.2, 1)    | Elements appearing      |
+ * | exit       | cubic-bezier(0.8, 0, 0.6, 1)  | Elements disappearing   |
+ */
 export declare const motionEasings: {
     readonly standard: "cubic-bezier(0.2, 0, 0, 1)";
     readonly emphasized: "cubic-bezier(0.33, 1, 0.68, 1)";
     readonly entrance: "cubic-bezier(0, 0, 0.2, 1)";
     readonly exit: "cubic-bezier(0.8, 0, 0.6, 1)";
 };
+/**
+ * Union type of all available motion duration names.
+ */
 export type MotionDurationName = keyof typeof motionDurations;
+/**
+ * Union type of all available motion easing names.
+ */
 export type MotionEasingName = keyof typeof motionEasings;
+/**
+ * Returns the CSS custom property name for a motion duration.
+ *
+ * @param name - The motion duration name
+ * @returns The CSS variable name (e.g., `'--motion-duration-fast'`)
+ *
+ * @example
+ * ```ts
+ * getMotionDurationVarName('fast') // '--motion-duration-fast'
+ * ```
+ */
 export declare function getMotionDurationVarName(name: MotionDurationName): string;
+/**
+ * Returns a CSS `var()` expression referencing the motion duration custom property.
+ *
+ * @param name - The motion duration name
+ * @returns A CSS `var()` string (e.g., `'var(--motion-duration-fast)'`)
+ */
 export declare function getMotionDurationVar(name: MotionDurationName): string;
+/**
+ * Returns the CSS custom property name for the base motion duration.
+ *
+ * @returns The CSS variable name `'--motion-duration-base'`
+ */
+export declare function getBaseMotionDurationVarName(): string;
+/**
+ * Returns a CSS `var()` expression referencing the base motion duration custom property.
+ *
+ * @returns A CSS `var()` string `'var(--motion-duration-base)'`
+ */
+export declare function getBaseMotionDurationVar(): string;
+/**
+ * Returns the CSS custom property name for a motion easing curve.
+ *
+ * @param name - The motion easing name
+ * @returns The CSS variable name (e.g., `'--motion-easing-standard'`)
+ *
+ * @example
+ * ```ts
+ * getMotionEasingVarName('standard') // '--motion-easing-standard'
+ * ```
+ */
 export declare function getMotionEasingVarName(name: MotionEasingName): string;
+/**
+ * Returns a CSS `var()` expression referencing the motion easing custom property.
+ *
+ * @param name - The motion easing name
+ * @returns A CSS `var()` string (e.g., `'var(--motion-easing-standard)'`)
+ */
 export declare function getMotionEasingVar(name: MotionEasingName): string;
+/**
+ * Generates CSS custom property declarations for all motion tokens,
+ * including both durations and easing curves.
+ *
+ * @returns A record mapping CSS variable names to their values
+ *
+ * @example
+ * ```ts
+ * const vars = generateMotionVariables()
+ * // vars['--motion-duration-base'] === '200ms'
+ * // vars['--motion-duration-fast'] === 'calc(var(--motion-duration-base) * 0.6)'
+ * // vars['--motion-easing-standard'] === 'cubic-bezier(0.2, 0, 0, 1)'
+ * ```
+ */
 export declare function generateMotionVariables(): Record<string, string>;
+/**
+ * Tuple of all semantic motion role names, covering both transition
+ * durations and easing curves.
+ */
 export declare const semanticMotionNames: readonly ["transition-fast", "transition-medium", "transition-slow", "transition-overlay", "transition-emphasis", "easing-standard", "easing-emphasis", "easing-entrance", "easing-exit"];
+/**
+ * Union type of all semantic motion role names.
+ */
 export type SemanticMotionName = (typeof semanticMotionNames)[number];
+/**
+ * Partial record for overriding default semantic motion assignments.
+ */
 export type SemanticMotionOverrides = Partial<Record<SemanticMotionName, string>>;
+/**
+ * Returns the CSS custom property name for a semantic motion role.
+ *
+ * @param name - The semantic motion name
+ * @returns The CSS variable name (e.g., `'--motion-transition-fast'`)
+ *
+ * @example
+ * ```ts
+ * getSemanticMotionVarName('transition-fast') // '--motion-transition-fast'
+ * ```
+ */
 export declare function getSemanticMotionVarName(name: SemanticMotionName): string;
+/**
+ * Generates CSS custom property declarations for semantic motion tokens,
+ * merging defaults with any provided overrides.
+ *
+ * @param overrides - Optional overrides for semantic motion values
+ * @returns A record mapping CSS variable names to their values
+ *
+ * @example
+ * ```ts
+ * const vars = generateSemanticMotionVariables({ 'transition-fast': '80ms' })
+ * // vars['--motion-transition-fast'] === '80ms'
+ * ```
+ */
 export declare function generateSemanticMotionVariables(overrides?: SemanticMotionOverrides): Record<string, string>;

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

@@ -1,3 +1,26 @@
+/**
+ * Radius (border-radius) design tokens for BeatUI.
+ *
+ * Defines a scale of border-radius values based on the spacing base unit.
+ * Includes both primitive radius sizes and semantic radius roles for
+ * controls, surfaces, and overlays.
+ *
+ * @module
+ */
+/**
+ * Radius scale definitions mapping size names to CSS values.
+ * Values are expressed as multiples of the base spacing variable.
+ *
+ * | Name | Value                        | Approx |
+ * |------|------------------------------|--------|
+ * | none | 0                            | 0      |
+ * | xs   | base / 2                     | 2px    |
+ * | sm   | base                         | 4px    |
+ * | md   | base * 1.5                   | 6px    |
+ * | lg   | base * 2                     | 8px    |
+ * | xl   | base * 3                     | 12px   |
+ * | full | 9999px                       | pill   |
+ */
 export declare const radius: {
     readonly none: "0";
     readonly xs: "calc(var(--spacing-base) / 2)";
@@ -7,13 +30,89 @@ export declare const radius: {
     readonly xl: "calc(var(--spacing-base) * 3)";
     readonly full: "9999px";
 };
+/**
+ * Union type of all available radius size names.
+ */
 export type RadiusName = keyof typeof radius;
+/**
+ * Returns the CSS custom property name for a radius size.
+ *
+ * @param size - The radius size name
+ * @returns The CSS variable name (e.g., `'--radius-md'`)
+ *
+ * @example
+ * ```ts
+ * getRadiusVarName('md') // '--radius-md'
+ * ```
+ */
 export declare function getRadiusVarName(size: RadiusName): string;
+/**
+ * Returns a CSS `var()` expression referencing the radius custom property.
+ *
+ * @param size - The radius size name
+ * @returns A CSS `var()` string (e.g., `'var(--radius-md)'`)
+ *
+ * @example
+ * ```ts
+ * getRadiusVar('md') // 'var(--radius-md)'
+ * ```
+ */
 export declare function getRadiusVar(size: RadiusName): string;
+/**
+ * Returns a CSS media query string for a minimum-width breakpoint based on
+ * the radius value. Primarily used for internal utilities.
+ *
+ * @param size - The radius size name
+ * @returns A media query string
+ */
 export declare function getRadiusMediaQuery(size: RadiusName): string;
+/**
+ * Generates CSS custom property declarations for all radius tokens.
+ *
+ * @returns A record mapping CSS variable names to their radius values
+ *
+ * @example
+ * ```ts
+ * const vars = generateRadiusVariables()
+ * // vars['--radius-md'] === 'calc(var(--spacing-base) * 1.5)'
+ * ```
+ */
 export declare function generateRadiusVariables(): Record<string, string>;
+/**
+ * Tuple of all semantic radius role names.
+ */
 export declare const semanticRadiusNames: readonly ["control", "control-sm", "control-xs", "button", "surface", "overlay", "popover", "pill", "focus"];
+/**
+ * Union type of all semantic radius role names.
+ */
 export type SemanticRadiusName = (typeof semanticRadiusNames)[number];
+/**
+ * Partial record for overriding default semantic radius assignments.
+ */
 export type SemanticRadiusOverrides = Partial<Record<SemanticRadiusName, string>>;
+/**
+ * Returns the CSS custom property name for a semantic radius role.
+ *
+ * @param name - The semantic radius name
+ * @returns The CSS variable name (e.g., `'--radius-control'`)
+ *
+ * @example
+ * ```ts
+ * getSemanticRadiusVarName('button') // '--radius-button'
+ * ```
+ */
 export declare function getSemanticRadiusVarName(name: SemanticRadiusName): string;
+/**
+ * Generates CSS custom property declarations for semantic radius tokens,
+ * merging defaults with any provided overrides.
+ *
+ * @param overrides - Optional overrides for semantic radius values
+ * @returns A record mapping CSS variable names to their values
+ *
+ * @example
+ * ```ts
+ * const vars = generateSemanticRadiusVariables({ button: 'var(--radius-full)' })
+ * // vars['--radius-button'] === 'var(--radius-full)'
+ * ```
+ */
 export declare function generateSemanticRadiusVariables(overrides?: SemanticRadiusOverrides): Record<string, string>;

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

@@ -1,3 +1,19 @@
+/**
+ * Box shadow design tokens for BeatUI.
+ *
+ * Defines a scale of box-shadow values from subtle to dramatic, including both
+ * bottom-facing and top-facing shadow variants. Also includes semantic shadow
+ * roles for common UI surfaces.
+ *
+ * @module
+ */
+/**
+ * Box shadow scale definitions mapping size names to CSS `box-shadow` values.
+ * Includes standard (bottom-facing) and `top-*` (top-facing) variants.
+ *
+ * Standard shadows project downward; `top-*` shadows project upward
+ * and are useful for bottom-anchored elements like bottom sheets.
+ */
 export declare const shadows: {
     readonly none: "none";
     readonly '2xs': "0 1px rgb(0 0 0 / 0.05)";
@@ -15,12 +31,81 @@ export declare const shadows: {
     readonly 'top-xl': "0 -20px 25px -5px rgb(0 0 0 / 0.1), 0 8px 10px -6px rgb(0 0 0 / 0.1)";
     readonly 'top-2xl': "0 -25px 50px -12px rgb(0 0 0 / 0.25)";
 };
+/**
+ * Union type of all available shadow size names.
+ */
 export type ShadowSize = keyof typeof shadows;
+/**
+ * Returns the CSS custom property name for a shadow size.
+ *
+ * @param size - The shadow size name
+ * @returns The CSS variable name (e.g., `'--shadow-md'`)
+ *
+ * @example
+ * ```ts
+ * getShadowVarName('md') // '--shadow-md'
+ * ```
+ */
 export declare function getShadowVarName(size: ShadowSize): string;
+/**
+ * Returns a CSS `var()` expression referencing the shadow custom property.
+ *
+ * @param size - The shadow size name
+ * @returns A CSS `var()` string (e.g., `'var(--shadow-md)'`)
+ *
+ * @example
+ * ```ts
+ * getShadowVar('md') // 'var(--shadow-md)'
+ * ```
+ */
 export declare function getShadowVar(size: ShadowSize): string;
+/**
+ * Generates CSS custom property declarations for all shadow tokens.
+ *
+ * @returns A record mapping CSS variable names to their shadow values
+ *
+ * @example
+ * ```ts
+ * const vars = generateShadowVariables()
+ * // vars['--shadow-md'] === '0 4px 6px -1px rgb(0 0 0 / 0.1), ...'
+ * ```
+ */
 export declare function generateShadowVariables(): Record<string, string>;
+/**
+ * Tuple of all semantic shadow role names.
+ */
 export declare const semanticShadowNames: readonly ["surface", "surface-elevated", "popover", "overlay", "button"];
+/**
+ * Union type of all semantic shadow role names.
+ */
 export type SemanticShadowName = (typeof semanticShadowNames)[number];
+/**
+ * Partial record for overriding default semantic shadow assignments.
+ */
 export type SemanticShadowOverrides = Partial<Record<SemanticShadowName, string>>;
+/**
+ * Returns the CSS custom property name for a semantic shadow role.
+ *
+ * @param name - The semantic shadow name
+ * @returns The CSS variable name (e.g., `'--shadow-popover'`)
+ *
+ * @example
+ * ```ts
+ * getSemanticShadowVarName('popover') // '--shadow-popover'
+ * ```
+ */
 export declare function getSemanticShadowVarName(name: SemanticShadowName): string;
+/**
+ * Generates CSS custom property declarations for semantic shadow tokens,
+ * merging defaults with any provided overrides.
+ *
+ * @param overrides - Optional overrides for semantic shadow values
+ * @returns A record mapping CSS variable names to their values
+ *
+ * @example
+ * ```ts
+ * const vars = generateSemanticShadowVariables({ popover: 'var(--shadow-xl)' })
+ * // vars['--shadow-popover'] === 'var(--shadow-xl)'
+ * ```
+ */
 export declare function generateSemanticShadowVariables(overrides?: SemanticShadowOverrides): Record<string, string>;

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

@@ -1,24 +1,135 @@
+/**
+ * Spacing design tokens for BeatUI.
+ *
+ * Defines a spacing scale based on a configurable base unit (`0.25rem` by default).
+ * Spacing values are expressed as CSS `calc()` expressions referencing the base
+ * spacing variable, allowing the entire scale to be adjusted by changing a single value.
+ *
+ * @module
+ */
+/**
+ * The base spacing unit used as the foundation for the spacing scale.
+ *
+ * @default '0.25rem'
+ */
 export declare const baseSpacing = "0.25rem";
+/**
+ * Spacing scale definitions mapping size names to CSS values.
+ * All values (except `none`, `px`, `base`, and `full`) are computed
+ * as multiples of `var(--spacing-base)`.
+ *
+ * | Name | Value                            | Approx |
+ * |------|----------------------------------|--------|
+ * | none | 0                                | 0      |
+ * | px   | 1px                              | 1px    |
+ * | base | 0.25rem                          | 4px    |
+ * | xs   | base / 2                         | 2px    |
+ * | sm   | base                             | 4px    |
+ * | smh  | base * 1.5                       | 6px    |
+ * | md   | base * 2                         | 8px    |
+ * | mdh  | base * 3                         | 12px   |
+ * | lg   | base * 4                         | 16px   |
+ * | lgh  | base * 5                         | 20px   |
+ * | xl   | base * 6                         | 24px   |
+ * | 2xl  | base * 8                         | 32px   |
+ * | 2xlh | base * 10                        | 40px   |
+ * | 3xl  | base * 12                        | 48px   |
+ * | 4xl  | base * 16                        | 64px   |
+ * | full | 2000px                           | 2000px |
+ */
 export declare const spacing: {
     readonly none: "0";
     readonly px: "1px";
     readonly base: "0.25rem";
     readonly xs: "calc(var(--spacing-base) / 2)";
     readonly sm: "var(--spacing-base)";
+    readonly smh: "calc(var(--spacing-base) * 1.5)";
     readonly md: "calc(var(--spacing-base) * 2)";
+    readonly mdh: "calc(var(--spacing-base) * 3)";
     readonly lg: "calc(var(--spacing-base) * 4)";
+    readonly lgh: "calc(var(--spacing-base) * 5)";
     readonly xl: "calc(var(--spacing-base) * 6)";
     readonly '2xl': "calc(var(--spacing-base) * 8)";
+    readonly '2xlh': "calc(var(--spacing-base) * 10)";
     readonly '3xl': "calc(var(--spacing-base) * 12)";
     readonly '4xl': "calc(var(--spacing-base) * 16)";
     readonly full: "2000px";
 };
+/**
+ * Union type of all available spacing size names.
+ */
 export type SpacingName = keyof typeof spacing;
+/**
+ * Returns the CSS custom property name for a spacing size.
+ *
+ * @param size - The spacing size name
+ * @returns The CSS variable name (e.g., `'--spacing-md'`)
+ *
+ * @example
+ * ```ts
+ * getSpacingVarName('md') // '--spacing-md'
+ * ```
+ */
 export declare function getSpacingVarName(size: SpacingName): string;
+/**
+ * Returns a CSS `var()` expression referencing the spacing custom property.
+ *
+ * @param size - The spacing size name
+ * @returns A CSS `var()` string (e.g., `'var(--spacing-md)'`)
+ *
+ * @example
+ * ```ts
+ * getSpacingVar('md') // 'var(--spacing-md)'
+ * ```
+ */
 export declare function getSpacingVar(size: SpacingName): string;
+/**
+ * Generates CSS custom property declarations for all spacing tokens.
+ *
+ * @returns A record mapping CSS variable names to their spacing values
+ *
+ * @example
+ * ```ts
+ * const vars = generateSpacingVariables()
+ * // vars['--spacing-md'] === 'calc(var(--spacing-base) * 2)'
+ * ```
+ */
 export declare function generateSpacingVariables(): Record<string, string>;
+/**
+ * Tuple of all semantic spacing names, used for stack/gap spacing roles.
+ */
 export declare const semanticSpacingNames: readonly ["stack-2xs", "stack-xs", "stack-sm", "stack-md", "stack-lg", "stack-xl"];
+/**
+ * Union type of all semantic spacing names.
+ */
 export type SemanticSpacingName = (typeof semanticSpacingNames)[number];
+/**
+ * Partial record for overriding default semantic spacing values.
+ */
 export type SemanticSpacingOverrides = Partial<Record<SemanticSpacingName, string>>;
+/**
+ * Returns the CSS custom property name for a semantic spacing name.
+ *
+ * @param name - The semantic spacing name
+ * @returns The CSS variable name (e.g., `'--spacing-stack-md'`)
+ *
+ * @example
+ * ```ts
+ * getSemanticSpacingVarName('stack-md') // '--spacing-stack-md'
+ * ```
+ */
 export declare function getSemanticSpacingVarName(name: SemanticSpacingName): string;
+/**
+ * Generates CSS custom property declarations for semantic spacing tokens,
+ * merging defaults with any provided overrides.
+ *
+ * @param overrides - Optional overrides for semantic spacing values
+ * @returns A record mapping CSS variable names to their values
+ *
+ * @example
+ * ```ts
+ * const vars = generateSemanticSpacingVariables({ 'stack-md': '1rem' })
+ * // vars['--spacing-stack-md'] === '1rem'
+ * ```
+ */
 export declare function generateSemanticSpacingVariables(overrides?: SemanticSpacingOverrides): Record<string, string>;

package/dist/types/tokens/text-shadows.d.ts

@@ -1,3 +1,16 @@
+/**
+ * Text shadow design tokens for BeatUI.
+ *
+ * Defines a scale of CSS `text-shadow` values for enhancing text readability
+ * and visual depth. Includes both primitive size-based shadows and semantic
+ * roles for button text styles.
+ *
+ * @module
+ */
+/**
+ * Text shadow scale definitions mapping size names to CSS `text-shadow` values.
+ * Shadows increase in intensity from `2xs` (subtle) to `lg` (dramatic).
+ */
 export declare const textShadows: {
     readonly none: "none";
     readonly '2xs': "0px 1px 0px rgb(0 0 0 / 0.15)";
@@ -6,12 +19,81 @@ export declare const textShadows: {
     readonly md: "0px 1px 1px rgb(0 0 0 / 0.1), 0px 1px 2px rgb(0 0 0 / 0.1), 0px 2px 4px rgb(0 0 0 / 0.1)";
     readonly lg: "0px 1px 2px rgb(0 0 0 / 0.1), 0px 3px 2px rgb(0 0 0 / 0.1), 0px 4px 8px rgb(0 0 0 / 0.1)";
 };
+/**
+ * Union type of all available text shadow size names.
+ */
 export type TextShadowSize = keyof typeof textShadows;
+/**
+ * Tuple of all semantic text shadow role names.
+ */
 export declare const semanticTextShadowNames: readonly ["button-filled", "button-light", "button-default"];
+/**
+ * Union type of all semantic text shadow role names.
+ */
 export type SemanticTextShadowName = (typeof semanticTextShadowNames)[number];
+/**
+ * Partial record for overriding default semantic text shadow assignments.
+ */
 export type SemanticTextShadowOverrides = Partial<Record<SemanticTextShadowName, string>>;
+/**
+ * Returns the CSS custom property name for a text shadow size.
+ *
+ * @param size - The text shadow size name
+ * @returns The CSS variable name (e.g., `'--text-shadow-sm'`)
+ *
+ * @example
+ * ```ts
+ * getTextShadowVarName('sm') // '--text-shadow-sm'
+ * ```
+ */
 export declare function getTextShadowVarName(size: TextShadowSize): string;
+/**
+ * Returns a CSS `var()` expression referencing the text shadow custom property.
+ *
+ * @param size - The text shadow size name
+ * @returns A CSS `var()` string (e.g., `'var(--text-shadow-sm)'`)
+ *
+ * @example
+ * ```ts
+ * getTextShadowVar('sm') // 'var(--text-shadow-sm)'
+ * ```
+ */
 export declare function getTextShadowVar(size: TextShadowSize): string;
+/**
+ * Generates CSS custom property declarations for all text shadow tokens.
+ *
+ * @returns A record mapping CSS variable names to their text shadow values
+ *
+ * @example
+ * ```ts
+ * const vars = generateTextShadowVariables()
+ * // vars['--text-shadow-sm'] === '0px 1px 0px rgb(0 0 0 / 0.075), ...'
+ * ```
+ */
 export declare function generateTextShadowVariables(): Record<string, string>;
+/**
+ * Returns the CSS custom property name for a semantic text shadow role.
+ *
+ * @param name - The semantic text shadow name
+ * @returns The CSS variable name (e.g., `'--text-shadow-button-filled'`)
+ *
+ * @example
+ * ```ts
+ * getSemanticTextShadowVarName('button-filled') // '--text-shadow-button-filled'
+ * ```
+ */
 export declare function getSemanticTextShadowVarName(name: SemanticTextShadowName): string;
+/**
+ * Generates CSS custom property declarations for semantic text shadow tokens,
+ * merging defaults with any provided overrides.
+ *
+ * @param overrides - Optional overrides for semantic text shadow values
+ * @returns A record mapping CSS variable names to their values
+ *
+ * @example
+ * ```ts
+ * const vars = generateSemanticTextShadowVariables({ 'button-filled': 'var(--text-shadow-lg)' })
+ * // vars['--text-shadow-button-filled'] === 'var(--text-shadow-lg)'
+ * ```
+ */
 export declare function generateSemanticTextShadowVariables(overrides?: SemanticTextShadowOverrides): Record<string, string>;