@vivliostyle/core/lib/vivliostyle/counter-style.d.ts

Vivliostyle Core library for HTML+CSS typesetting with EPUB/Web publications support

/**
 * Copyright 2025 Vivliostyle Foundation
 *
 * Vivliostyle.js is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Affero General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * Vivliostyle.js is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Affero General Public License for more details.
 *
 * You should have received a copy of the GNU Affero General Public License
 * along with Vivliostyle.js.  If not, see <http://www.gnu.org/licenses/>.
 */
/**
 * Not implemented:
 *
 * - Support using <image> in <symbol>
 *     https://drafts.csswg.org/css-counter-styles/#typedef-symbol
 *
 * - Make the disclosure-open/closed values respond to writing modes
 *     https://drafts.csswg.org/css-counter-styles/#disclosure-open
 *   CounterStyle.format may require the writing mode as an argument.
 *   It may be necessary to extend it so that the caller can obtain the writing mode.
 *
 * - Use grapheme clusters for character counting in CounterStyle.#applyPadding.
 *     https://drafts.csswg.org/css-counter-styles/#counter-style-pad
 *   Intl.Segmenter may be useful. CounterStyle.format may require the lang as an argument.
 *
 * - Implement symbols() for defining anonymous counter styles
 *     https://drafts.csswg.org/css-counter-styles/#symbols-function
 *   Extending CounterStyle.defineAnonymous( ... ) should work.
 */
import * as Css from "./css";
import * as CssCascade from "./css-cascade";
type SetElement<T> = T extends ReadonlySet<infer U> ? U : never;
type Negative = Readonly<{
    prefix: string;
    suffix: string | null;
}>;
type RangeItem = Readonly<{
    lower: number;
    upper: number;
}>;
type Range = readonly [RangeItem, ...RangeItem[]];
type Pad = Readonly<{
    minLength: number;
    symbol: string;
}>;
type AdditiveSymbol = Readonly<{
    weight: number;
    symbol: string;
}>;
/**
 * @see https://drafts.csswg.org/css-counter-styles/
 */
export declare function validateDescriptorValue(name: string, value: Css.Val): boolean;
type CounterStyleStoreMap = Map<string, CounterStyle>;
declare abstract class CounterStyle {
    #private;
    protected readonly _store: CounterStyleStoreMap;
    protected constructor(store: CounterStyleStoreMap, descriptors: CssCascade.ElementStyle);
    static create(store: CounterStyleStoreMap, descriptors: CssCascade.ElementStyle): CounterStyle;
    static createDecimal(store: CounterStyleStoreMap): CounterStyle;
    static createDisc(store: CounterStyleStoreMap): CounterStyle;
    static createSquare(store: CounterStyleStoreMap): CounterStyle;
    static createCircle(store: CounterStyleStoreMap): CounterStyle;
    static createDisclosureOpen(store: CounterStyleStoreMap): CounterStyle;
    static createDisclosureClosed(store: CounterStyleStoreMap): CounterStyle;
    static createNone(store: CounterStyleStoreMap): CounterStyle;
    static get CHINESE_LONGHAND_NAMES(): typeof ChineseLonghand.NAMES;
    static createChineseLonghand(store: CounterStyleStoreMap, name: SetElement<typeof ChineseLonghand.NAMES>): CounterStyle;
    static createEthiopicNumeric(store: CounterStyleStoreMap): CounterStyle;
    protected _getNegative(): Negative | null;
    protected static _getNegativeFrom(style: CounterStyle): Negative | null;
    protected _getPrefix(): string | null;
    protected static _getPrefixFrom(style: CounterStyle): string | null;
    protected _getSuffix(): string | null;
    protected static _getSuffixFrom(style: CounterStyle): string | null;
    protected abstract _getAutoRange(): Range;
    protected static _getAutoRangeFrom(style: CounterStyle): Range;
    protected _getRange(): Range | null;
    protected static _getRangeFrom(style: CounterStyle): Range | null;
    protected _getPad(): Pad | null;
    protected static _getPadFrom(style: CounterStyle): Pad | null;
    protected _getFallback(): CounterStyle | null;
    protected static _getFallbackFrom(style: CounterStyle): CounterStyle | null;
    protected _getSymbols(): readonly [string, ...string[]] | null;
    protected static _getSymbolsFrom(style: CounterStyle): readonly [string, ...string[]] | null;
    protected _getAdditiveSymbols(): readonly [AdditiveSymbol, ...AdditiveSymbol[]] | null;
    protected static _getAdditiveSymbolsFrom(style: CounterStyle): readonly [AdditiveSymbol, ...AdditiveSymbol[]] | null;
    /**
     * @see https://drafts.csswg.org/css-counter-styles-3/#use-a-negative-sign
     */
    protected abstract _usesNegativeSign(value: number): boolean;
    protected static _useNegativeSignFrom(style: CounterStyle, value: number): boolean;
    /**
     * @see https://drafts.csswg.org/css-counter-styles-3/#generate-a-counter
     */
    protected abstract _generateInitialRepresentation(value: number): string | null;
    protected static _generateInitialRepresentationFrom(style: CounterStyle, value: number): string | null;
    /**
     * Format a counter value to its string representation.
     * @see https://drafts.csswg.org/css-counter-styles-3/#generate-a-counter
     */
    format(value: number): string;
    /**
     * Format a counter value with prefix and suffix for use in ::marker.
     * Unlike format(), this includes the prefix and suffix descriptors.
     * @see https://drafts.csswg.org/css-counter-styles-3/#counter-style-prefix
     * @see https://drafts.csswg.org/css-counter-styles-3/#counter-style-suffix
     */
    formatMarker(value: number): string;
}
declare const chineseLonghandNameList: readonly ["simp-chinese-informal", "simp-chinese-formal", "trad-chinese-informal", "trad-chinese-formal", "cjk-ideographic"];
/**
 * @see https://drafts.csswg.org/css-counter-styles-3/#limited-chinese
 */
declare class ChineseLonghand extends CounterStyle {
    #private;
    static readonly NAMES: ReadonlySet<(typeof chineseLonghandNameList)[number]>;
    constructor(store: CounterStyleStoreMap, name: SetElement<typeof ChineseLonghand.NAMES>);
    protected _getAutoRange(): Range;
    protected _usesNegativeSign(value: number): boolean;
    protected _generateInitialRepresentation(value: number): string | null;
}
export declare class CounterStyleStore {
    #private;
    constructor();
    define(name: string, descriptors: CssCascade.ElementStyle): CounterStyle | null;
    getStyle(name: string): CounterStyle | null;
    /**
     * Format a counter value using the specified counter style.
     * @see https://drafts.csswg.org/css-counter-styles/
     */
    format(name: string, value: number): string;
    /**
     * Format a counter value with prefix and suffix for use in ::marker.
     * Not yet in use, but will be used in the future. #732
     * @see https://drafts.csswg.org/css-counter-styles/
     */
    formatMarker(name: string, value: number): string;
}
export {};