@pixerate/editor 0.160.0 → 0.162.0

package/dist/typography/accessibility.d.cts

@@ -0,0 +1,44 @@
+/**
+ * Contrast checks that know the type: WCAG 2 large-text eligibility comes from the font's size and
+ * weight, so callers never have to decide whether text is "large".
+ */
+import type { ContrastLevel } from '../color/types.cjs';
+import type { FontWeight } from './types.cjs';
+/** WCAG 2 large text: 18pt (24px) regular, or 14pt (18.67px) bold. */
+export declare const LARGE_TEXT_PX = 24;
+export declare const LARGE_BOLD_TEXT_PX: number;
+/** Whether text counts as large for WCAG 2 contrast (size in CSS px). */
+export declare function isLargeText(font: {
+    size: number;
+    weight?: FontWeight;
+}): boolean;
+export interface TypographyAccessibilityResult {
+    /** WCAG 2 contrast ratio, 1–21. */
+    ratio: number;
+    large: boolean;
+    level: ContrastLevel;
+    passesAA: boolean;
+    passesAAA: boolean;
+    /** Ratios this text needs: 4.5 / 7 for normal text, 3 / 4.5 for large text. */
+    required: {
+        AA: number;
+        AAA: number;
+    };
+    /** A foreground (hex) at the nearest OKLCH lightness that passes AA, when AA fails. */
+    suggestion?: string;
+    /** Smallest size in px that would count as large text at this weight. */
+    largeTextMinSize: number;
+    issues: string[];
+}
+/**
+ * Checks text colour against its background using the type's real size and weight: decides large
+ * text, reports the required ratios, and suggests a passing foreground when AA fails.
+ */
+export declare function checkTypographyAccessibility(options: {
+    font: {
+        size: number;
+        weight?: FontWeight;
+    };
+    foreground: string;
+    background: string;
+}): TypographyAccessibilityResult;

package/dist/typography/accessibility.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Contrast checks that know the type: WCAG 2 large-text eligibility comes from the font's size and
+ * weight, so callers never have to decide whether text is "large".
+ */
+import type { ContrastLevel } from '../color/types.js';
+import type { FontWeight } from './types.js';
+/** WCAG 2 large text: 18pt (24px) regular, or 14pt (18.67px) bold. */
+export declare const LARGE_TEXT_PX = 24;
+export declare const LARGE_BOLD_TEXT_PX: number;
+/** Whether text counts as large for WCAG 2 contrast (size in CSS px). */
+export declare function isLargeText(font: {
+    size: number;
+    weight?: FontWeight;
+}): boolean;
+export interface TypographyAccessibilityResult {
+    /** WCAG 2 contrast ratio, 1–21. */
+    ratio: number;
+    large: boolean;
+    level: ContrastLevel;
+    passesAA: boolean;
+    passesAAA: boolean;
+    /** Ratios this text needs: 4.5 / 7 for normal text, 3 / 4.5 for large text. */
+    required: {
+        AA: number;
+        AAA: number;
+    };
+    /** A foreground (hex) at the nearest OKLCH lightness that passes AA, when AA fails. */
+    suggestion?: string;
+    /** Smallest size in px that would count as large text at this weight. */
+    largeTextMinSize: number;
+    issues: string[];
+}
+/**
+ * Checks text colour against its background using the type's real size and weight: decides large
+ * text, reports the required ratios, and suggests a passing foreground when AA fails.
+ */
+export declare function checkTypographyAccessibility(options: {
+    font: {
+        size: number;
+        weight?: FontWeight;
+    };
+    foreground: string;
+    background: string;
+}): TypographyAccessibilityResult;

package/dist/typography/catalog.d.cts

@@ -0,0 +1,98 @@
+/**
+ * Font catalogs and the built-in providers: a metadata catalog of common system fonts (no font
+ * files), a system provider that can use the Local Font Access API when the host opts in, and a
+ * web font provider that loads faces through the CSS Font Loading API. Browser APIs are injectable
+ * so headless hosts and tests never touch the network.
+ */
+import type { FontCategory, FontStyle, FontWeight } from './types.cjs';
+import { type FontPlatform, type FontProvider, type FontSummary } from './registry.cjs';
+/** Metadata for widely installed system fonts. No font files are bundled. */
+export declare const SYSTEM_FONT_CATALOG: readonly FontSummary[];
+/** Platforms the catalog covers. */
+export declare const FONT_PLATFORMS: readonly FontPlatform[];
+/** The catalog category of a family, or a guess from its name (`Mono`, `Code`, `Serif`, `Script`…). */
+export declare function guessFontCategory(family: string): FontCategory;
+/** An in-memory provider over a fixed list (a design system's families, a test fixture). */
+export declare function createCatalogFontProvider(fonts: readonly FontSummary[], options?: {
+    id?: string;
+}): FontProvider;
+/** The Local Font Access API's entries (`queryLocalFonts()`), as far as this module reads them. */
+export interface LocalFontDataLike {
+    family: string;
+    style?: string;
+    fullName?: string;
+}
+export interface SystemFontProviderOptions {
+    id?: string;
+    /** Catalog to offer (default {@link SYSTEM_FONT_CATALOG}). */
+    catalog?: readonly FontSummary[];
+    /** Offer only fonts that ship on this platform. */
+    platform?: FontPlatform;
+    /**
+     * Lists the fonts actually installed (the Local Font Access API, which asks the user for
+     * permission). Not called unless given: pass `() => window.queryLocalFonts()` to opt in.
+     */
+    queryLocalFonts?: () => Promise<readonly LocalFontDataLike[]>;
+}
+/**
+ * System fonts. Without `queryLocalFonts` it offers the catalog (filtered by `platform`): what is
+ * commonly installed, not what this machine has. With it, it offers what the machine reports,
+ * categorised from the catalog or by name.
+ *
+ * `hasFont` never uses `document.fonts.check()`: it answers `true` for families that are not
+ * installed at all (see GOTCHAS "[core/typography] `document.fonts.check()` …").
+ */
+export declare function createSystemFontProvider(options?: SystemFontProviderOptions): FontProvider;
+/** One file of a web font family. */
+export interface WebFontSource {
+    /** URL of the font file (woff2 preferred). */
+    url: string;
+    /** Weight, or a `[min, max]` range for a variable font (default 400). */
+    weight?: FontWeight | [number, number];
+    /** Default `normal`. */
+    style?: FontStyle;
+    /** CSS `format()` hint, e.g. `woff2`. */
+    format?: string;
+    /** CSS `unicode-range` descriptor. */
+    unicodeRange?: string;
+}
+export interface WebFontDefinition {
+    family: string;
+    category: FontCategory;
+    sources: readonly WebFontSource[];
+    /** CSS `font-display` (default `swap`). */
+    display?: 'auto' | 'block' | 'swap' | 'fallback' | 'optional';
+}
+/** The parts of the CSS Font Loading API (`FontFace`, `document.fonts`) the web provider uses. */
+export interface FontFaceLike {
+    load(): Promise<unknown>;
+}
+export interface FontFaceSetLike {
+    add(face: any): unknown;
+}
+export type CreateFontFace = (family: string, source: string, descriptors: {
+    weight: string;
+    style: string;
+    display: string;
+    unicodeRange?: string;
+}) => FontFaceLike;
+export interface WebFontProviderOptions {
+    id?: string;
+    fonts: readonly WebFontDefinition[];
+    /** Where loaded faces are added (default `document.fonts` when there is a document). */
+    fontFaceSet?: FontFaceSetLike;
+    /** Builds a face (default `new FontFace(...)` when the runtime has it). Inject a fake in tests: nothing then hits the network. */
+    createFontFace?: CreateFontFace;
+}
+/** `@font-face` rules for a definition, for server rendering or a stylesheet. */
+export declare function fontFaceCss(def: WebFontDefinition): string;
+/** The summary a definition lists as. */
+export declare function webFontSummary(def: WebFontDefinition): FontSummary;
+/**
+ * Web fonts loaded on demand through the CSS Font Loading API. `loadFont` picks the source that
+ * best matches the weight and style, adds the face to the font set and resolves when it is ready
+ * (`false` if it fails or there is no `FontFace` in this runtime). Loads are cached per face.
+ */
+export declare function createWebFontProvider(options: WebFontProviderOptions): FontProvider & {
+    loaded(family: string, weight?: FontWeight, style?: FontStyle): boolean;
+};

package/dist/typography/catalog.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Font catalogs and the built-in providers: a metadata catalog of common system fonts (no font
+ * files), a system provider that can use the Local Font Access API when the host opts in, and a
+ * web font provider that loads faces through the CSS Font Loading API. Browser APIs are injectable
+ * so headless hosts and tests never touch the network.
+ */
+import type { FontCategory, FontStyle, FontWeight } from './types.js';
+import { type FontPlatform, type FontProvider, type FontSummary } from './registry.js';
+/** Metadata for widely installed system fonts. No font files are bundled. */
+export declare const SYSTEM_FONT_CATALOG: readonly FontSummary[];
+/** Platforms the catalog covers. */
+export declare const FONT_PLATFORMS: readonly FontPlatform[];
+/** The catalog category of a family, or a guess from its name (`Mono`, `Code`, `Serif`, `Script`…). */
+export declare function guessFontCategory(family: string): FontCategory;
+/** An in-memory provider over a fixed list (a design system's families, a test fixture). */
+export declare function createCatalogFontProvider(fonts: readonly FontSummary[], options?: {
+    id?: string;
+}): FontProvider;
+/** The Local Font Access API's entries (`queryLocalFonts()`), as far as this module reads them. */
+export interface LocalFontDataLike {
+    family: string;
+    style?: string;
+    fullName?: string;
+}
+export interface SystemFontProviderOptions {
+    id?: string;
+    /** Catalog to offer (default {@link SYSTEM_FONT_CATALOG}). */
+    catalog?: readonly FontSummary[];
+    /** Offer only fonts that ship on this platform. */
+    platform?: FontPlatform;
+    /**
+     * Lists the fonts actually installed (the Local Font Access API, which asks the user for
+     * permission). Not called unless given: pass `() => window.queryLocalFonts()` to opt in.
+     */
+    queryLocalFonts?: () => Promise<readonly LocalFontDataLike[]>;
+}
+/**
+ * System fonts. Without `queryLocalFonts` it offers the catalog (filtered by `platform`): what is
+ * commonly installed, not what this machine has. With it, it offers what the machine reports,
+ * categorised from the catalog or by name.
+ *
+ * `hasFont` never uses `document.fonts.check()`: it answers `true` for families that are not
+ * installed at all (see GOTCHAS "[core/typography] `document.fonts.check()` …").
+ */
+export declare function createSystemFontProvider(options?: SystemFontProviderOptions): FontProvider;
+/** One file of a web font family. */
+export interface WebFontSource {
+    /** URL of the font file (woff2 preferred). */
+    url: string;
+    /** Weight, or a `[min, max]` range for a variable font (default 400). */
+    weight?: FontWeight | [number, number];
+    /** Default `normal`. */
+    style?: FontStyle;
+    /** CSS `format()` hint, e.g. `woff2`. */
+    format?: string;
+    /** CSS `unicode-range` descriptor. */
+    unicodeRange?: string;
+}
+export interface WebFontDefinition {
+    family: string;
+    category: FontCategory;
+    sources: readonly WebFontSource[];
+    /** CSS `font-display` (default `swap`). */
+    display?: 'auto' | 'block' | 'swap' | 'fallback' | 'optional';
+}
+/** The parts of the CSS Font Loading API (`FontFace`, `document.fonts`) the web provider uses. */
+export interface FontFaceLike {
+    load(): Promise<unknown>;
+}
+export interface FontFaceSetLike {
+    add(face: any): unknown;
+}
+export type CreateFontFace = (family: string, source: string, descriptors: {
+    weight: string;
+    style: string;
+    display: string;
+    unicodeRange?: string;
+}) => FontFaceLike;
+export interface WebFontProviderOptions {
+    id?: string;
+    fonts: readonly WebFontDefinition[];
+    /** Where loaded faces are added (default `document.fonts` when there is a document). */
+    fontFaceSet?: FontFaceSetLike;
+    /** Builds a face (default `new FontFace(...)` when the runtime has it). Inject a fake in tests: nothing then hits the network. */
+    createFontFace?: CreateFontFace;
+}
+/** `@font-face` rules for a definition, for server rendering or a stylesheet. */
+export declare function fontFaceCss(def: WebFontDefinition): string;
+/** The summary a definition lists as. */
+export declare function webFontSummary(def: WebFontDefinition): FontSummary;
+/**
+ * Web fonts loaded on demand through the CSS Font Loading API. `loadFont` picks the source that
+ * best matches the weight and style, adds the face to the font set and resolves when it is ready
+ * (`false` if it fails or there is no `FontFace` in this runtime). Loads are cached per face.
+ */
+export declare function createWebFontProvider(options: WebFontProviderOptions): FontProvider & {
+    loaded(family: string, weight?: FontWeight, style?: FontStyle): boolean;
+};