@pixerate/editor 0.160.0 → 0.162.0

package/dist/typography/metrics.d.cts

@@ -0,0 +1,31 @@
+/**
+ * Measure (line length), line spacing and other readability checks for body text.
+ */
+import type { FontCategory, FontSpec, ReadabilityAuditResult } from './types.cjs';
+/** Comfortable measure for body text, in characters per line. */
+export declare const OPTIMAL_MEASURE: {
+    readonly min: 45;
+    readonly max: 75;
+};
+/** WCAG 1.4.8 (AAA) line spacing and the WCAG 1.4.12 test value: 1.5× the font size. */
+export declare const RECOMMENDED_LINE_HEIGHT = 1.5;
+/** Silent reading speed used for reading time (words per minute). */
+export declare const READING_WORDS_PER_MINUTE = 238;
+/** Line-height browsers use for `normal` with most fonts, assumed when none is given. */
+export declare const ASSUMED_NORMAL_LINE_HEIGHT = 1.2;
+/** Estimated characters per line for a container width (px) at a font size, from average glyph widths. */
+export declare function estimateCharactersPerLine(width: number, font: {
+    size: number;
+    category?: FontCategory;
+    letterSpacing?: number;
+}): number;
+export interface ReadabilityOptions extends Partial<FontSpec> {
+    /** Container width in px; when given with `size`, line length is estimated from it instead of the text's own line breaks. */
+    width?: number;
+}
+/**
+ * Audits body text: line length against 45–75 characters, line spacing against 1.5, text set in
+ * capitals, and reading time. Line length comes from the text's own lines, or from `width` and
+ * `size` when both are given.
+ */
+export declare function auditTextReadability(text: string, font?: ReadabilityOptions): ReadabilityAuditResult;

package/dist/typography/metrics.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Measure (line length), line spacing and other readability checks for body text.
+ */
+import type { FontCategory, FontSpec, ReadabilityAuditResult } from './types.js';
+/** Comfortable measure for body text, in characters per line. */
+export declare const OPTIMAL_MEASURE: {
+    readonly min: 45;
+    readonly max: 75;
+};
+/** WCAG 1.4.8 (AAA) line spacing and the WCAG 1.4.12 test value: 1.5× the font size. */
+export declare const RECOMMENDED_LINE_HEIGHT = 1.5;
+/** Silent reading speed used for reading time (words per minute). */
+export declare const READING_WORDS_PER_MINUTE = 238;
+/** Line-height browsers use for `normal` with most fonts, assumed when none is given. */
+export declare const ASSUMED_NORMAL_LINE_HEIGHT = 1.2;
+/** Estimated characters per line for a container width (px) at a font size, from average glyph widths. */
+export declare function estimateCharactersPerLine(width: number, font: {
+    size: number;
+    category?: FontCategory;
+    letterSpacing?: number;
+}): number;
+export interface ReadabilityOptions extends Partial<FontSpec> {
+    /** Container width in px; when given with `size`, line length is estimated from it instead of the text's own line breaks. */
+    width?: number;
+}
+/**
+ * Audits body text: line length against 45–75 characters, line spacing against 1.5, text set in
+ * capitals, and reading time. Line length comes from the text's own lines, or from `width` and
+ * `size` when both are given.
+ */
+export declare function auditTextReadability(text: string, font?: ReadabilityOptions): ReadabilityAuditResult;

package/dist/typography/picker.d.cts

@@ -0,0 +1,132 @@
+/**
+ * Headless font picker model shared by the React and Svelte bindings: the selected family, weight,
+ * style and metrics, category filter and search, recent families, highlight navigation for a
+ * combobox, and per-family load status. DOM-free.
+ */
+import { type FontProvider, type FontSummary } from './registry.cjs';
+import type { FontCategory, FontSpec, FontStyle, FontWeight, NumericFontWeight } from './types.cjs';
+export type FontLoadStatus = 'idle' | 'loading' | 'loaded' | 'failed';
+export interface FontPickerState {
+    /** The selected value. */
+    value: Required<Pick<FontSpec, 'family' | 'size' | 'style' | 'lineHeight' | 'letterSpacing'>> & {
+        weight: NumericFontWeight;
+        category?: FontCategory;
+    };
+    /** Category filter (`all` for none). */
+    category: FontCategory | 'all';
+    query: string;
+    /** Every font the picker knows. */
+    fonts: readonly FontSummary[];
+    /** `fonts` after the category filter and search. */
+    results: readonly FontSummary[];
+    /** Recently chosen families that are still in `fonts`, newest first. */
+    recent: readonly FontSummary[];
+    /** Index into `results` of the highlighted option (-1 for none). */
+    highlighted: number;
+    previewText: string;
+    /** Whether `fonts` is being fetched from the provider. */
+    loading: boolean;
+    /** Provider error message from the last refresh. */
+    error?: string;
+    /** Load status of each family's preview face, by lower-cased family. */
+    loadStatus: Readonly<Record<string, FontLoadStatus>>;
+}
+export interface FontPickerOptions {
+    /** Where fonts come from. Without one, pass `fonts`. */
+    provider?: FontProvider;
+    /** A fixed list (used until `refresh()` replaces it from the provider). */
+    fonts?: readonly FontSummary[];
+    /** Initial value. Default: the first font at 16px. */
+    value?: Partial<FontSpec>;
+    /** Initial recent families, newest first. */
+    recent?: readonly string[];
+    /** Most recent families kept (default 8). */
+    maxRecent?: number;
+    previewText?: string;
+    /** Load a family's face through the provider when it is selected (default true). */
+    loadOnSelect?: boolean;
+    /** Called whenever the value changes (not on filter or search changes). */
+    onChange?: (value: FontSpec) => void;
+}
+/** Weights a font offers (every weight in range for a variable font; all nine when unknown). */
+export declare function offeredWeights(font: FontSummary | undefined): NumericFontWeight[];
+export declare const DEFAULT_PREVIEW_TEXT = "The quick brown fox jumps over the lazy dog";
+export declare class FontPickerModel {
+    private state;
+    private readonly listeners;
+    private readonly valueListeners;
+    private recentFamilies;
+    private destroyed;
+    readonly provider?: FontProvider;
+    private readonly maxRecent;
+    private readonly loadOnSelect;
+    private readonly onChange?;
+    constructor(options?: FontPickerOptions);
+    /** The current state. The same object is returned until something changes. */
+    getState: () => FontPickerState;
+    /** Calls `listener` after every change; returns an unsubscribe function. */
+    subscribe: (listener: (state: FontPickerState) => void) => (() => void);
+    /**
+     * Calls `listener` when the value changes through the picker or its agent tools (not through
+     * `setValue`, so a controlled component does not echo its own updates). Returns an unsubscribe.
+     */
+    onValueChange: (listener: (value: FontSpec) => void) => (() => void);
+    /** The selected value as a {@link FontSpec}. */
+    get value(): FontSpec;
+    /** The selected family's summary, if it is in `fonts`. */
+    get selectedFont(): FontSummary | undefined;
+    /** Weights the selected family offers (all nine when unknown or variable). */
+    get availableWeights(): NumericFontWeight[];
+    /** Styles the selected family offers (`normal` when unknown). */
+    get availableStyles(): FontStyle[];
+    /** CSS for the selection: a fallback-resolved `font-family` plus the other properties. */
+    get css(): {
+        fontFamily: string;
+        fontWeight: string;
+        fontStyle: string;
+        fontSize: string;
+        lineHeight: string;
+        letterSpacing: string;
+    };
+    /** A `font-family` value for previewing any family in a list. */
+    familyCss(font: FontSummary | string): string;
+    /** Fetches fonts from the provider. Keeps the current list when it fails. */
+    refresh(): Promise<readonly FontSummary[]>;
+    setQuery(query: string): void;
+    setCategory(category: FontCategory | 'all'): void;
+    setPreviewText(previewText: string): void;
+    /**
+     * Selects a family. Throws when `fonts` is non-empty and does not list it. Keeps the weight if
+     * the family has it, else picks the nearest one; keeps the style if offered, else `normal`.
+     */
+    selectFamily(family: string): void;
+    /** Sets the weight; snaps to the nearest weight the family offers. */
+    setWeight(weight: FontWeight | number): void;
+    setStyle(style: FontStyle): void;
+    /** Font size in px, clamped to 1–1000. */
+    setSize(size: number): void;
+    /** Unitless line-height, clamped to 0.5–4. */
+    setLineHeight(lineHeight: number): void;
+    /** Tracking in em, clamped to -0.5–1. */
+    setLetterSpacing(letterSpacing: number): void;
+    /** Replaces the value (for controlled components). Does not call `onChange` or touch recents. */
+    setValue(value: Partial<FontSpec>): void;
+    /** Moves the highlight through `results` (wraps around). */
+    moveHighlight(delta: number): void;
+    setHighlight(index: number): void;
+    /** Selects the highlighted result. Returns whether there was one. */
+    commitHighlight(): boolean;
+    /**
+     * Handles combobox keys (ArrowDown/ArrowUp/Home/End/Enter/Escape). Returns whether the key was
+     * handled, so the caller can `preventDefault`.
+     */
+    handleKey(key: string): boolean;
+    /** Loads a family's face through the provider (for previews) and tracks its status. */
+    loadFamily(family: string, weight?: FontWeight, style?: FontStyle): Promise<boolean>;
+    destroy(): void;
+    private commit;
+    private derive;
+    private set;
+}
+/** Creates a {@link FontPickerModel}. */
+export declare function createFontPicker(options?: FontPickerOptions): FontPickerModel;

package/dist/typography/picker.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Headless font picker model shared by the React and Svelte bindings: the selected family, weight,
+ * style and metrics, category filter and search, recent families, highlight navigation for a
+ * combobox, and per-family load status. DOM-free.
+ */
+import { type FontProvider, type FontSummary } from './registry.js';
+import type { FontCategory, FontSpec, FontStyle, FontWeight, NumericFontWeight } from './types.js';
+export type FontLoadStatus = 'idle' | 'loading' | 'loaded' | 'failed';
+export interface FontPickerState {
+    /** The selected value. */
+    value: Required<Pick<FontSpec, 'family' | 'size' | 'style' | 'lineHeight' | 'letterSpacing'>> & {
+        weight: NumericFontWeight;
+        category?: FontCategory;
+    };
+    /** Category filter (`all` for none). */
+    category: FontCategory | 'all';
+    query: string;
+    /** Every font the picker knows. */
+    fonts: readonly FontSummary[];
+    /** `fonts` after the category filter and search. */
+    results: readonly FontSummary[];
+    /** Recently chosen families that are still in `fonts`, newest first. */
+    recent: readonly FontSummary[];
+    /** Index into `results` of the highlighted option (-1 for none). */
+    highlighted: number;
+    previewText: string;
+    /** Whether `fonts` is being fetched from the provider. */
+    loading: boolean;
+    /** Provider error message from the last refresh. */
+    error?: string;
+    /** Load status of each family's preview face, by lower-cased family. */
+    loadStatus: Readonly<Record<string, FontLoadStatus>>;
+}
+export interface FontPickerOptions {
+    /** Where fonts come from. Without one, pass `fonts`. */
+    provider?: FontProvider;
+    /** A fixed list (used until `refresh()` replaces it from the provider). */
+    fonts?: readonly FontSummary[];
+    /** Initial value. Default: the first font at 16px. */
+    value?: Partial<FontSpec>;
+    /** Initial recent families, newest first. */
+    recent?: readonly string[];
+    /** Most recent families kept (default 8). */
+    maxRecent?: number;
+    previewText?: string;
+    /** Load a family's face through the provider when it is selected (default true). */
+    loadOnSelect?: boolean;
+    /** Called whenever the value changes (not on filter or search changes). */
+    onChange?: (value: FontSpec) => void;
+}
+/** Weights a font offers (every weight in range for a variable font; all nine when unknown). */
+export declare function offeredWeights(font: FontSummary | undefined): NumericFontWeight[];
+export declare const DEFAULT_PREVIEW_TEXT = "The quick brown fox jumps over the lazy dog";
+export declare class FontPickerModel {
+    private state;
+    private readonly listeners;
+    private readonly valueListeners;
+    private recentFamilies;
+    private destroyed;
+    readonly provider?: FontProvider;
+    private readonly maxRecent;
+    private readonly loadOnSelect;
+    private readonly onChange?;
+    constructor(options?: FontPickerOptions);
+    /** The current state. The same object is returned until something changes. */
+    getState: () => FontPickerState;
+    /** Calls `listener` after every change; returns an unsubscribe function. */
+    subscribe: (listener: (state: FontPickerState) => void) => (() => void);
+    /**
+     * Calls `listener` when the value changes through the picker or its agent tools (not through
+     * `setValue`, so a controlled component does not echo its own updates). Returns an unsubscribe.
+     */
+    onValueChange: (listener: (value: FontSpec) => void) => (() => void);
+    /** The selected value as a {@link FontSpec}. */
+    get value(): FontSpec;
+    /** The selected family's summary, if it is in `fonts`. */
+    get selectedFont(): FontSummary | undefined;
+    /** Weights the selected family offers (all nine when unknown or variable). */
+    get availableWeights(): NumericFontWeight[];
+    /** Styles the selected family offers (`normal` when unknown). */
+    get availableStyles(): FontStyle[];
+    /** CSS for the selection: a fallback-resolved `font-family` plus the other properties. */
+    get css(): {
+        fontFamily: string;
+        fontWeight: string;
+        fontStyle: string;
+        fontSize: string;
+        lineHeight: string;
+        letterSpacing: string;
+    };
+    /** A `font-family` value for previewing any family in a list. */
+    familyCss(font: FontSummary | string): string;
+    /** Fetches fonts from the provider. Keeps the current list when it fails. */
+    refresh(): Promise<readonly FontSummary[]>;
+    setQuery(query: string): void;
+    setCategory(category: FontCategory | 'all'): void;
+    setPreviewText(previewText: string): void;
+    /**
+     * Selects a family. Throws when `fonts` is non-empty and does not list it. Keeps the weight if
+     * the family has it, else picks the nearest one; keeps the style if offered, else `normal`.
+     */
+    selectFamily(family: string): void;
+    /** Sets the weight; snaps to the nearest weight the family offers. */
+    setWeight(weight: FontWeight | number): void;
+    setStyle(style: FontStyle): void;
+    /** Font size in px, clamped to 1–1000. */
+    setSize(size: number): void;
+    /** Unitless line-height, clamped to 0.5–4. */
+    setLineHeight(lineHeight: number): void;
+    /** Tracking in em, clamped to -0.5–1. */
+    setLetterSpacing(letterSpacing: number): void;
+    /** Replaces the value (for controlled components). Does not call `onChange` or touch recents. */
+    setValue(value: Partial<FontSpec>): void;
+    /** Moves the highlight through `results` (wraps around). */
+    moveHighlight(delta: number): void;
+    setHighlight(index: number): void;
+    /** Selects the highlighted result. Returns whether there was one. */
+    commitHighlight(): boolean;
+    /**
+     * Handles combobox keys (ArrowDown/ArrowUp/Home/End/Enter/Escape). Returns whether the key was
+     * handled, so the caller can `preventDefault`.
+     */
+    handleKey(key: string): boolean;
+    /** Loads a family's face through the provider (for previews) and tracks its status. */
+    loadFamily(family: string, weight?: FontWeight, style?: FontStyle): Promise<boolean>;
+    destroy(): void;
+    private commit;
+    private derive;
+    private set;
+}
+/** Creates a {@link FontPickerModel}. */
+export declare function createFontPicker(options?: FontPickerOptions): FontPickerModel;

package/dist/typography/registry.d.cts

@@ -0,0 +1,66 @@
+/**
+ * Pluggable font providers: the interface hosts implement (system fonts, a web font service, a
+ * design system's own families), filtering, and a combinator that merges several providers.
+ */
+import type { FontCategory, FontSource, FontStyle, FontWeight } from './types.cjs';
+export type FontPlatform = 'macos' | 'windows' | 'ios' | 'android' | 'linux';
+export interface FontSummary {
+    family: string;
+    category: FontCategory;
+    weights: FontWeight[];
+    styles: FontStyle[];
+    /** A variable font: any weight between the lowest and highest in `weights` works. */
+    isVariable?: boolean;
+    source: FontSource;
+    /** Platforms that ship it, for system fonts. */
+    platforms?: FontPlatform[];
+}
+export interface FontProvider {
+    readonly id: string;
+    /** Every font the provider offers. */
+    listFonts(): Promise<FontSummary[]>;
+    /** Whether the provider offers (system) or has loaded (web) the family. */
+    hasFont(family: string): boolean | Promise<boolean>;
+    /** Makes a face usable for rendering; resolves `true` when it is ready, `false` when it cannot be loaded. */
+    loadFont?(family: string, weight?: FontWeight, style?: FontStyle): Promise<boolean>;
+}
+export interface FontFilter {
+    category?: FontCategory;
+    source?: FontSource;
+    /** Keep fonts that offer this weight (variable fonts: within their range). */
+    weight?: FontWeight;
+    style?: FontStyle;
+    /** Case-insensitive substring of the family name. */
+    query?: string;
+    isVariable?: boolean;
+}
+/** Whether a font offers a weight (variable fonts offer every weight in their range). */
+export declare function fontHasWeight(font: FontSummary, weight: FontWeight): boolean;
+/**
+ * Filters fonts. With a `query`, families that start with it come first, then the rest that
+ * contain it; otherwise the order is kept.
+ */
+export declare function filterFonts(fonts: readonly FontSummary[], filter?: FontFilter): FontSummary[];
+/** Finds a family by name, case-insensitively. */
+export declare function findFont(fonts: readonly FontSummary[], family: string): FontSummary | undefined;
+/**
+ * One provider over several: fonts are merged by family (case-insensitive; the first provider
+ * that lists a family wins), `hasFont` asks each in turn, and `loadFont` uses the first
+ * provider that lists the family and can load.
+ */
+export declare function combineFontProviders(providers: readonly FontProvider[], options?: {
+    id?: string;
+}): FontProvider;
+export interface EnsureFontsResult {
+    loaded: string[];
+    failed: string[];
+}
+/**
+ * Loads every face a set of specs needs before rendering (for example before rasterising a title
+ * preview, so the first frame does not use a fallback font). Duplicates are loaded once.
+ */
+export declare function ensureFontsLoaded(provider: FontProvider, specs: ReadonlyArray<{
+    family: string;
+    weight?: FontWeight;
+    style?: FontStyle;
+}>): Promise<EnsureFontsResult>;

package/dist/typography/registry.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Pluggable font providers: the interface hosts implement (system fonts, a web font service, a
+ * design system's own families), filtering, and a combinator that merges several providers.
+ */
+import type { FontCategory, FontSource, FontStyle, FontWeight } from './types.js';
+export type FontPlatform = 'macos' | 'windows' | 'ios' | 'android' | 'linux';
+export interface FontSummary {
+    family: string;
+    category: FontCategory;
+    weights: FontWeight[];
+    styles: FontStyle[];
+    /** A variable font: any weight between the lowest and highest in `weights` works. */
+    isVariable?: boolean;
+    source: FontSource;
+    /** Platforms that ship it, for system fonts. */
+    platforms?: FontPlatform[];
+}
+export interface FontProvider {
+    readonly id: string;
+    /** Every font the provider offers. */
+    listFonts(): Promise<FontSummary[]>;
+    /** Whether the provider offers (system) or has loaded (web) the family. */
+    hasFont(family: string): boolean | Promise<boolean>;
+    /** Makes a face usable for rendering; resolves `true` when it is ready, `false` when it cannot be loaded. */
+    loadFont?(family: string, weight?: FontWeight, style?: FontStyle): Promise<boolean>;
+}
+export interface FontFilter {
+    category?: FontCategory;
+    source?: FontSource;
+    /** Keep fonts that offer this weight (variable fonts: within their range). */
+    weight?: FontWeight;
+    style?: FontStyle;
+    /** Case-insensitive substring of the family name. */
+    query?: string;
+    isVariable?: boolean;
+}
+/** Whether a font offers a weight (variable fonts offer every weight in their range). */
+export declare function fontHasWeight(font: FontSummary, weight: FontWeight): boolean;
+/**
+ * Filters fonts. With a `query`, families that start with it come first, then the rest that
+ * contain it; otherwise the order is kept.
+ */
+export declare function filterFonts(fonts: readonly FontSummary[], filter?: FontFilter): FontSummary[];
+/** Finds a family by name, case-insensitively. */
+export declare function findFont(fonts: readonly FontSummary[], family: string): FontSummary | undefined;
+/**
+ * One provider over several: fonts are merged by family (case-insensitive; the first provider
+ * that lists a family wins), `hasFont` asks each in turn, and `loadFont` uses the first
+ * provider that lists the family and can load.
+ */
+export declare function combineFontProviders(providers: readonly FontProvider[], options?: {
+    id?: string;
+}): FontProvider;
+export interface EnsureFontsResult {
+    loaded: string[];
+    failed: string[];
+}
+/**
+ * Loads every face a set of specs needs before rendering (for example before rasterising a title
+ * preview, so the first frame does not use a fallback font). Duplicates are loaded once.
+ */
+export declare function ensureFontsLoaded(provider: FontProvider, specs: ReadonlyArray<{
+    family: string;
+    weight?: FontWeight;
+    style?: FontStyle;
+}>): Promise<EnsureFontsResult>;

package/dist/typography/scale.d.cts

@@ -0,0 +1,62 @@
+/**
+ * Modular type scales, a standard heading-to-caption hierarchy, and fluid (viewport-scaled) sizes.
+ */
+import type { ModularScaleRatio, TypeHierarchy, TypeScaleStep } from './types.cjs';
+/** The named ratios and their values. */
+export declare const MODULAR_SCALE_RATIOS: Readonly<Record<ModularScaleRatio, number>>;
+export declare const MODULAR_SCALE_RATIO_NAMES: ModularScaleRatio[];
+/** Token names of the standard hierarchy, by step (caption −2 … display 5). */
+export declare const TYPE_HIERARCHY_STEPS: Readonly<Record<string, number>>;
+/** The value of a named ratio. Throws for an unknown name. */
+export declare function getScaleRatio(name: ModularScaleRatio): number;
+/** A ratio as a number: named ratios are looked up, numbers must be above 1 and at most 4. */
+export declare function resolveScaleRatio(ratio: number | ModularScaleRatio): number;
+/**
+ * Recommended unitless line-height for a size: 1.5 up to 16px (body text, WCAG 1.4.8), easing
+ * to 1.1 at 64px and above (display type), in steps of 0.05.
+ */
+export declare function recommendedLineHeight(size: number): number;
+/** Recommended tracking in em: looser for small text, tighter for large headings. */
+export declare function recommendedLetterSpacing(size: number): number;
+/** One step of a scale: `baseSize × ratio^step`, with recommended line-height and tracking. */
+export declare function typeScaleStep(baseSize: number, ratio: number, step: number, name?: string): TypeScaleStep;
+/** A modular scale: one {@link TypeScaleStep} per requested step, in the order given. */
+export declare function computeTypeScale(baseSize: number, ratio: number | ModularScaleRatio, steps?: readonly number[]): TypeScaleStep[];
+/** Tokens `caption`, `body-sm`, `body`, `h4`, `h3`, `h2`, `h1` and `display` on one modular scale. */
+export declare function generateTypeHierarchy(options?: {
+    baseSize?: number;
+    ratio?: ModularScaleRatio | number;
+}): TypeHierarchy;
+/**
+ * CSS custom properties for a hierarchy: `--<prefix>-<name>-size` (rem), `-line-height` and
+ * `-letter-spacing` (em) per token, inside `selector` (default `:root`).
+ */
+export declare function typeHierarchyToCss(hierarchy: TypeHierarchy, options?: {
+    prefix?: string;
+    selector?: string;
+    rootFontSize?: number;
+}): string;
+export interface FluidSizeOptions {
+    /** Size in px at `minViewport` and below. */
+    minSize: number;
+    /** Size in px at `maxViewport` and above. */
+    maxSize: number;
+    /** Viewport width in px where scaling starts. */
+    minViewport: number;
+    /** Viewport width in px where scaling stops. */
+    maxViewport: number;
+    /** Root font size in px used to express rem values (default 16). */
+    rootFontSize?: number;
+}
+export interface FluidSize {
+    /** `clamp(min, intercept + slope·vw, max)` with rem bounds, so user zoom and font settings still apply. */
+    clampCss: string;
+    /** Growth per viewport px (px of font per px of viewport). */
+    slope: number;
+    /** Intercept in px (the size the linear part gives at a zero-width viewport). */
+    intercept: number;
+    /** The size in px at a viewport width. */
+    evaluateAt: (viewport: number) => number;
+}
+/** A size that scales linearly with the viewport between two widths, as a CSS `clamp()`. */
+export declare function computeFluidSize(options: FluidSizeOptions): FluidSize;

package/dist/typography/scale.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Modular type scales, a standard heading-to-caption hierarchy, and fluid (viewport-scaled) sizes.
+ */
+import type { ModularScaleRatio, TypeHierarchy, TypeScaleStep } from './types.js';
+/** The named ratios and their values. */
+export declare const MODULAR_SCALE_RATIOS: Readonly<Record<ModularScaleRatio, number>>;
+export declare const MODULAR_SCALE_RATIO_NAMES: ModularScaleRatio[];
+/** Token names of the standard hierarchy, by step (caption −2 … display 5). */
+export declare const TYPE_HIERARCHY_STEPS: Readonly<Record<string, number>>;
+/** The value of a named ratio. Throws for an unknown name. */
+export declare function getScaleRatio(name: ModularScaleRatio): number;
+/** A ratio as a number: named ratios are looked up, numbers must be above 1 and at most 4. */
+export declare function resolveScaleRatio(ratio: number | ModularScaleRatio): number;
+/**
+ * Recommended unitless line-height for a size: 1.5 up to 16px (body text, WCAG 1.4.8), easing
+ * to 1.1 at 64px and above (display type), in steps of 0.05.
+ */
+export declare function recommendedLineHeight(size: number): number;
+/** Recommended tracking in em: looser for small text, tighter for large headings. */
+export declare function recommendedLetterSpacing(size: number): number;
+/** One step of a scale: `baseSize × ratio^step`, with recommended line-height and tracking. */
+export declare function typeScaleStep(baseSize: number, ratio: number, step: number, name?: string): TypeScaleStep;
+/** A modular scale: one {@link TypeScaleStep} per requested step, in the order given. */
+export declare function computeTypeScale(baseSize: number, ratio: number | ModularScaleRatio, steps?: readonly number[]): TypeScaleStep[];
+/** Tokens `caption`, `body-sm`, `body`, `h4`, `h3`, `h2`, `h1` and `display` on one modular scale. */
+export declare function generateTypeHierarchy(options?: {
+    baseSize?: number;
+    ratio?: ModularScaleRatio | number;
+}): TypeHierarchy;
+/**
+ * CSS custom properties for a hierarchy: `--<prefix>-<name>-size` (rem), `-line-height` and
+ * `-letter-spacing` (em) per token, inside `selector` (default `:root`).
+ */
+export declare function typeHierarchyToCss(hierarchy: TypeHierarchy, options?: {
+    prefix?: string;
+    selector?: string;
+    rootFontSize?: number;
+}): string;
+export interface FluidSizeOptions {
+    /** Size in px at `minViewport` and below. */
+    minSize: number;
+    /** Size in px at `maxViewport` and above. */
+    maxSize: number;
+    /** Viewport width in px where scaling starts. */
+    minViewport: number;
+    /** Viewport width in px where scaling stops. */
+    maxViewport: number;
+    /** Root font size in px used to express rem values (default 16). */
+    rootFontSize?: number;
+}
+export interface FluidSize {
+    /** `clamp(min, intercept + slope·vw, max)` with rem bounds, so user zoom and font settings still apply. */
+    clampCss: string;
+    /** Growth per viewport px (px of font per px of viewport). */
+    slope: number;
+    /** Intercept in px (the size the linear part gives at a zero-width viewport). */
+    intercept: number;
+    /** The size in px at a viewport width. */
+    evaluateAt: (viewport: number) => number;
+}
+/** A size that scales linearly with the viewport between two widths, as a CSS `clamp()`. */
+export declare function computeFluidSize(options: FluidSizeOptions): FluidSize;

package/dist/typography/segment.d.cts

@@ -0,0 +1,26 @@
+/**
+ * Host-agnostic text segmentation (graphemes, words, sentences, lines) with UTF-16 offsets, so
+ * live text can be split for staggered animation without converting it to outlines.
+ */
+import type { SegmentGranularity, TextSegment } from './types.cjs';
+export interface SegmentTextOptions {
+    /** BCP 47 locale for `Intl.Segmenter` (default: the runtime's). */
+    locale?: string;
+    /** For `word`: return only word-like segments, dropping white space and punctuation (default false). */
+    wordsOnly?: boolean;
+    /**
+     * For `line`: wrap each hard line greedily at word boundaries so no line exceeds this many
+     * characters (a word longer than that gets a line of its own). Omit to split on line breaks only.
+     */
+    maxCharacters?: number;
+}
+/** Grapheme clusters as strings (falls back to code points without `Intl.Segmenter`). */
+export declare function graphemes(text: string, locale?: string): string[];
+/** Number of user-perceived characters (grapheme clusters). */
+export declare function countGraphemes(text: string, locale?: string): number;
+/**
+ * Splits text into graphemes, words, sentences or lines. Offsets are UTF-16 indexes into `text`,
+ * so `text.slice(start, end) === segment.text`. `line` splits on line breaks (and wraps when
+ * `maxCharacters` is set); it cannot know how a renderer will wrap without a measure.
+ */
+export declare function segmentText(text: string, granularity: SegmentGranularity, options?: SegmentTextOptions): TextSegment[];

package/dist/typography/segment.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Host-agnostic text segmentation (graphemes, words, sentences, lines) with UTF-16 offsets, so
+ * live text can be split for staggered animation without converting it to outlines.
+ */
+import type { SegmentGranularity, TextSegment } from './types.js';
+export interface SegmentTextOptions {
+    /** BCP 47 locale for `Intl.Segmenter` (default: the runtime's). */
+    locale?: string;
+    /** For `word`: return only word-like segments, dropping white space and punctuation (default false). */
+    wordsOnly?: boolean;
+    /**
+     * For `line`: wrap each hard line greedily at word boundaries so no line exceeds this many
+     * characters (a word longer than that gets a line of its own). Omit to split on line breaks only.
+     */
+    maxCharacters?: number;
+}
+/** Grapheme clusters as strings (falls back to code points without `Intl.Segmenter`). */
+export declare function graphemes(text: string, locale?: string): string[];
+/** Number of user-perceived characters (grapheme clusters). */
+export declare function countGraphemes(text: string, locale?: string): number;
+/**
+ * Splits text into graphemes, words, sentences or lines. Offsets are UTF-16 indexes into `text`,
+ * so `text.slice(start, end) === segment.text`. `line` splits on line breaks (and wraps when
+ * `maxCharacters` is set); it cannot know how a renderer will wrap without a measure.
+ */
+export declare function segmentText(text: string, granularity: SegmentGranularity, options?: SegmentTextOptions): TextSegment[];