@ariaui/typography 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,365 @@
+/**
+ * A complete text style definition.
+ */
+interface TextStyle {
+    /** Font size, e.g. `"1rem"`, `"clamp(1rem, 0.5rem + 1.5vw, 1.5rem)"` */
+    readonly fontSize: string;
+    /** Line height, e.g. `"1.5rem"` */
+    readonly lineHeight: string;
+    /** Letter spacing, e.g. `"-0.02em"`, `"0em"` */
+    readonly letterSpacing: string;
+    /** Font weight, e.g. `"400"`, `"600"` */
+    readonly fontWeight?: string;
+    /** Font family, e.g. `"'Inter', sans-serif"` */
+    readonly fontFamily?: string;
+}
+/**
+ * A single step in a type scale. Mirrors `TypeStep` from `@ariaui/tokens`
+ * but kept independent so the core package has no dependency.
+ */
+interface ScaleStep {
+    /** Font size in rem, e.g. `"1rem"` */
+    readonly size: string;
+    /** Line height in rem, e.g. `"1.5rem"` */
+    readonly lineHeight: string;
+    /** Letter spacing in em, e.g. `"-0.02em"` */
+    readonly letterSpacing: string;
+    /** Recommended font weight */
+    readonly fontWeight?: string;
+}
+/**
+ * Configuration for CSS `clamp()`-based fluid typography.
+ */
+interface FluidConfig {
+    /** Minimum font size in rem */
+    readonly minSize: number;
+    /** Maximum font size in rem */
+    readonly maxSize: number;
+    /** Minimum viewport width in px (default 320) */
+    readonly minViewport?: number;
+    /** Maximum viewport width in px (default 1280) */
+    readonly maxViewport?: number;
+}
+/**
+ * A font stack definition.
+ */
+interface FontStack {
+    /** Human-readable name, e.g. `"sans"` */
+    readonly name: string;
+    /** Ordered list of font families */
+    readonly families: readonly string[];
+}
+/**
+ * Breakpoint name → pixel value mapping.
+ */
+type Breakpoints = Record<string, number>;
+/**
+ * A responsive text style: default + optional breakpoint overrides.
+ */
+interface ResponsiveTextStyle {
+    /** Base style (no media query) */
+    readonly default: TextStyle;
+    /** Keyed by breakpoint name */
+    readonly breakpoints: Record<string, TextStyle>;
+}
+/**
+ * Configuration for vertical rhythm / baseline grid.
+ */
+interface BaselineConfig {
+    /** Baseline grid unit in rem (default 0.25 — 4px at 16px root) */
+    readonly gridUnit?: number;
+    /** Rounding strategy: `"ceil"` rounds up, `"round"` rounds to nearest, `"floor"` rounds down */
+    readonly rounding?: "ceil" | "round" | "floor";
+}
+
+/** Pre-defined modular scale ratios. */
+declare const RATIOS: {
+    readonly minorSecond: 1.067;
+    readonly majorSecond: 1.125;
+    readonly minorThird: 1.2;
+    readonly majorThird: 1.25;
+    readonly perfectFourth: 1.333;
+    readonly augmentedFourth: 1.414;
+    readonly perfectFifth: 1.5;
+    readonly goldenRatio: 1.618;
+};
+/**
+ * Create a modular type scale.
+ *
+ * Generates `steps` sizes by multiplying a base size by the ratio.
+ * Steps are named with a numeric index (0 = base, positive = larger,
+ * negative = smaller).
+ *
+ * @param base  - Base font size in rem (default 1)
+ * @param ratio - Scale ratio (use `RATIOS` or a custom number)
+ * @param stepsUp   - Number of steps above the base (default 5)
+ * @param stepsDown - Number of steps below the base (default 2)
+ *
+ * @example
+ * createModularScale(1, RATIOS.perfectFourth, 5, 2)
+ * // → { "-2": ..., "-1": ..., "0": ..., "1": ..., ... "5": ... }
+ */
+declare function createModularScale(base?: number, ratio?: number, stepsUp?: number, stepsDown?: number): Record<string, ScaleStep>;
+/**
+ * Extend an existing scale with overrides.
+ *
+ * Each override is shallowly merged with the existing step (if present)
+ * or added as a new step.
+ */
+declare function extendScale(base: Record<string, ScaleStep>, overrides: Record<string, Partial<ScaleStep>>): Record<string, ScaleStep>;
+/**
+ * Get a single step from a scale by name.
+ */
+declare function getStep(scale: Record<string, ScaleStep>, name: string): ScaleStep | undefined;
+/**
+ * List all step names in a scale, sorted by font size (smallest first).
+ */
+declare function listSteps(scale: Record<string, ScaleStep>): string[];
+
+/**
+ * Generate a CSS `clamp()` value for fluid typography.
+ *
+ * Uses the formula:
+ * ```
+ * clamp(minSize, preferredValue, maxSize)
+ * ```
+ * where `preferredValue = baseRem + slopeVw`
+ *
+ * @example
+ * fluidSize({ minSize: 1, maxSize: 1.5 })
+ * // → "clamp(1rem, 0.7667rem + 0.7292vw, 1.5rem)"
+ */
+declare function fluidSize(config: FluidConfig): string;
+/**
+ * Generate a fluid `TextStyle` by interpolating between a min and max `ScaleStep`.
+ *
+ * Font size uses `clamp()`, line-height and letter-spacing use the max step values.
+ *
+ * @param min - Scale step at the minimum viewport
+ * @param max - Scale step at the maximum viewport
+ * @param viewports - Optional min/max viewport widths in px
+ */
+declare function fluidStyle(min: ScaleStep, max: ScaleStep, viewports?: {
+    min?: number;
+    max?: number;
+}): TextStyle;
+/**
+ * Make an entire scale fluid between mobile and desktop sizes.
+ *
+ * Both scales must have matching keys. For each key, a fluid style
+ * is generated by interpolating the mobile step to the desktop step.
+ *
+ * @param mobileScale  - Scale at the minimum viewport
+ * @param desktopScale - Scale at the maximum viewport
+ * @param viewports    - Optional min/max viewport widths in px
+ */
+declare function fluidScale(mobileScale: Record<string, ScaleStep>, desktopScale: Record<string, ScaleStep>, viewports?: {
+    min?: number;
+    max?: number;
+}): Record<string, TextStyle>;
+
+/** System UI font stack — uses the OS default sans-serif. */
+declare const systemStack: FontStack;
+/** Sans-serif stack with Inter as the primary font. */
+declare const sansStack: FontStack;
+/** Serif font stack. */
+declare const serifStack: FontStack;
+/** Monospace font stack. */
+declare const monoStack: FontStack;
+/** All pre-defined stacks keyed by name. */
+declare const FONT_STACKS: Record<string, FontStack>;
+/**
+ * Build a CSS `font-family` value from a `FontStack`.
+ *
+ * @example
+ * buildFontFamily(sansStack)
+ * // → "'Inter', system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif"
+ */
+declare function buildFontFamily(stack: FontStack): string;
+/**
+ * Create a custom font stack.
+ *
+ * @param name     - Stack identifier
+ * @param primary  - Primary font family (will be quoted if needed)
+ * @param fallback - Base fallback stack to append (default: `systemStack`)
+ */
+declare function createFontStack(name: string, primary: string, fallback?: FontStack): FontStack;
+
+/**
+ * Create a `TextStyle` from a `ScaleStep` with optional overrides.
+ *
+ * @example
+ * createTextStyle({ size: "1rem", lineHeight: "1.5rem", letterSpacing: "0em" })
+ * // → { fontSize: "1rem", lineHeight: "1.5rem", letterSpacing: "0em" }
+ *
+ * createTextStyle(step, { fontWeight: "700", fontFamily: "'Inter', sans-serif" })
+ */
+declare function createTextStyle(step: ScaleStep, overrides?: Partial<TextStyle>): TextStyle;
+/**
+ * Merge multiple partial text styles. Later values win.
+ *
+ * Undefined properties are omitted from the result unless a later
+ * style provides them.
+ *
+ * @example
+ * mergeTextStyles(
+ *   { fontSize: "1rem", lineHeight: "1.5rem", letterSpacing: "0em" },
+ *   { fontWeight: "700" },
+ * )
+ */
+declare function mergeTextStyles(...styles: Partial<TextStyle>[]): TextStyle;
+
+/**
+ * Convert a `TextStyle` to a React `CSSProperties` object.
+ *
+ * @example
+ * toCSSProperties(style)
+ * // → { fontSize: "1rem", lineHeight: "1.5rem", letterSpacing: "0em" }
+ */
+declare function toCSSProperties(style: TextStyle): Record<string, string>;
+/**
+ * Convert a `TextStyle` to a CSS declaration block string.
+ *
+ * @example
+ * toCSSDeclarations(style)
+ * // → "font-size: 1rem;\nline-height: 1.5rem;\nletter-spacing: 0em;"
+ */
+declare function toCSSDeclarations(style: TextStyle): string;
+/**
+ * Generate CSS using `var()` references to `@ariaui/tokens` CSS custom properties.
+ *
+ * @param stepName - Token step name, e.g. `"display-2xl"`, `"text-md"`
+ *
+ * @example
+ * toCSSVars("display-2xl")
+ * // → "font-size: var(--font-size-display-2xl);\nline-height: var(--font-size-display-2xl--line-height);\nletter-spacing: var(--font-size-display-2xl--letter-spacing);"
+ */
+declare function toCSSVars(stepName: string): string;
+/**
+ * Convert a `TextStyle` to Tailwind CSS arbitrary-value classes.
+ *
+ * @example
+ * toTailwindClasses(style)
+ * // → "text-[1rem] leading-[1.5rem] tracking-[0em]"
+ */
+declare function toTailwindClasses(style: TextStyle): string;
+
+/**
+ * Default breakpoints matching Tailwind CSS v4 defaults.
+ */
+declare const BREAKPOINTS: Breakpoints;
+/**
+ * Build a `ResponsiveTextStyle` from a map of breakpoint → scale step or text style.
+ *
+ * The `"default"` key is required; all other keys must match a breakpoint name.
+ *
+ * @param config      - Map of `"default"` + breakpoint names to `ScaleStep` or `TextStyle`
+ * @param breakpoints - Breakpoint definitions (default: Tailwind breakpoints)
+ *
+ * @example
+ * responsiveStyle({
+ *   default: { size: "0.875rem", lineHeight: "1.25rem", letterSpacing: "0em" },
+ *   md: { size: "1rem", lineHeight: "1.5rem", letterSpacing: "0em" },
+ *   lg: { size: "1.125rem", lineHeight: "1.75rem", letterSpacing: "0em" },
+ * })
+ */
+declare function responsiveStyle(config: Record<string, ScaleStep | TextStyle>, breakpoints?: Breakpoints): ResponsiveTextStyle;
+/**
+ * Get the sorted breakpoint entries from a `ResponsiveTextStyle`,
+ * ordered by viewport width (ascending).
+ *
+ * Useful for consumers that need to iterate breakpoints in order.
+ *
+ * @returns Array of `[breakpointName, pixelWidth, textStyle]` tuples.
+ */
+declare function sortedBreakpoints(responsive: ResponsiveTextStyle, breakpoints?: Breakpoints): Array<[string, number, TextStyle]>;
+
+/**
+ * Calculate the optimal line length in `ch` units.
+ *
+ * Based on the typographic guideline of **45–75 characters per line**
+ * (Bringhurst). The ideal is ~66 characters.
+ *
+ * The font-size parameter is accepted for API consistency but the
+ * recommended range is font-size-independent when using `ch` units
+ * (which scale with the font).
+ *
+ * @param options.min - Minimum characters per line (default 45)
+ * @param options.max - Maximum characters per line (default 75)
+ * @param options.ideal - Ideal characters per line (default 66)
+ *
+ * @returns The ideal measure as a `ch` string.
+ *
+ * @example
+ * optimalMeasure()          // → "66ch"
+ * optimalMeasure({ ideal: 60 }) // → "60ch"
+ */
+declare function optimalMeasure(options?: {
+    min?: number;
+    max?: number;
+    ideal?: number;
+}): string;
+/**
+ * Get the full measure range as min/max `ch` values.
+ *
+ * Useful for setting `min-width` / `max-width` on a reading container.
+ *
+ * @example
+ * measureRange() // → { min: "45ch", max: "75ch", ideal: "66ch" }
+ */
+declare function measureRange(options?: {
+    min?: number;
+    max?: number;
+    ideal?: number;
+}): {
+    min: string;
+    max: string;
+    ideal: string;
+};
+/**
+ * Snap a line-height to a baseline grid.
+ *
+ * Given a font size and a grid unit (default 0.25rem = 4px), returns
+ * the smallest line-height that:
+ * 1. Is a multiple of `gridUnit`
+ * 2. Is ≥ the font size × minimum line-height ratio (default 1.2)
+ *
+ * @param fontSize  - Font size as a rem string (e.g. `"1rem"`)
+ * @param config    - Baseline grid configuration
+ *
+ * @example
+ * snapToBaseline("1rem")       // → "1.5rem"  (1.5 = 6 × 0.25)
+ * snapToBaseline("2.25rem")    // → "2.75rem" (2.75 = 11 × 0.25)
+ * snapToBaseline("1rem", { gridUnit: 0.5 }) // → "1.5rem"
+ */
+declare function snapToBaseline(fontSize: string, config?: BaselineConfig): string;
+/**
+ * Calculate the vertical spacing (margin/padding) needed to maintain
+ * rhythm between elements on a baseline grid.
+ *
+ * @param lineHeight - Current line-height as a rem string
+ * @param lines      - Number of grid lines of spacing (default 1)
+ * @param gridUnit   - Grid unit in rem (default 0.25)
+ *
+ * @example
+ * rhythmSpacing("1.5rem")       // → "0.25rem" (one 4px grid line)
+ * rhythmSpacing("1.5rem", 2)    // → "0.5rem"  (two grid lines)
+ * rhythmSpacing("1.5rem", 4)    // → "1rem"    (four grid lines = 16px)
+ */
+declare function rhythmSpacing(lineHeight: string, lines?: number, gridUnit?: number): string;
+/**
+ * Generate a complete vertical rhythm configuration for a text style.
+ *
+ * Returns the snapped line-height plus recommended spacing above and below.
+ *
+ * @param fontSize    - Font size as a rem string
+ * @param spacingLines - Lines of spacing between paragraphs (default 4 = 1rem)
+ * @param config       - Baseline grid configuration
+ */
+declare function verticalRhythm(fontSize: string, spacingLines?: number, config?: BaselineConfig): {
+    lineHeight: string;
+    marginTop: string;
+    marginBottom: string;
+};
+
+export { BREAKPOINTS, type BaselineConfig, type Breakpoints, FONT_STACKS, type FluidConfig, type FontStack, RATIOS, type ResponsiveTextStyle, type ScaleStep, type TextStyle, buildFontFamily, createFontStack, createModularScale, createTextStyle, extendScale, fluidScale, fluidSize, fluidStyle, getStep, listSteps, measureRange, mergeTextStyles, monoStack, optimalMeasure, responsiveStyle, rhythmSpacing, sansStack, serifStack, snapToBaseline, sortedBreakpoints, systemStack, toCSSDeclarations, toCSSProperties, toCSSVars, toTailwindClasses, verticalRhythm };

package/dist/index.js

@@ -0,0 +1,62 @@
+import {
+  BREAKPOINTS,
+  FONT_STACKS,
+  RATIOS,
+  buildFontFamily,
+  createFontStack,
+  createModularScale,
+  createTextStyle,
+  extendScale,
+  fluidScale,
+  fluidSize,
+  fluidStyle,
+  getStep,
+  listSteps,
+  measureRange,
+  mergeTextStyles,
+  monoStack,
+  optimalMeasure,
+  responsiveStyle,
+  rhythmSpacing,
+  sansStack,
+  serifStack,
+  snapToBaseline,
+  sortedBreakpoints,
+  systemStack,
+  toCSSDeclarations,
+  toCSSProperties,
+  toCSSVars,
+  toTailwindClasses,
+  verticalRhythm
+} from "./chunk-F7KWOKBZ.js";
+export {
+  BREAKPOINTS,
+  FONT_STACKS,
+  RATIOS,
+  buildFontFamily,
+  createFontStack,
+  createModularScale,
+  createTextStyle,
+  extendScale,
+  fluidScale,
+  fluidSize,
+  fluidStyle,
+  getStep,
+  listSteps,
+  measureRange,
+  mergeTextStyles,
+  monoStack,
+  optimalMeasure,
+  responsiveStyle,
+  rhythmSpacing,
+  sansStack,
+  serifStack,
+  snapToBaseline,
+  sortedBreakpoints,
+  systemStack,
+  toCSSDeclarations,
+  toCSSProperties,
+  toCSSVars,
+  toTailwindClasses,
+  verticalRhythm
+};