@tangram.gl/tangram-renderer 0.0.0-stage → 0.0.0

package/src/styles/text/text_labels.ts

@@ -0,0 +1,436 @@
+// Tangram
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2013-2016 Brett Camper and Mapzen
+// Copyright (c) 2026 vis.gl contributors
+
+// Text label rendering methods, can be mixed into a rendering style
+
+
+import StyleParser from '../style_parser';
+import type {LabelLayout} from '../../labels/label-types';
+import type {TextSettingsResult} from './text_settings';
+import type {TextLabelState, TextLabelDraw, TextFeature, TextContext, TextTile, TextFeatureQueue, TextLabelCandidate, ParsedTextFeature, TextTable, TextSourceValue, TextValue, TextAtlas} from './text-types';
+
+/** Typed boundary to the legacy property-cache parser, not a replacement implementation. */
+const typedStyleParser = StyleParser as unknown as {
+    createPropertyCache(value: unknown, parse?: (value: unknown) => unknown, interpolate?: (value: unknown) => unknown): unknown;
+    parsePositiveNumber(value: unknown): number;
+    parseNumber(value: unknown): number;
+};
+/** Host style state plus the checked text-label operations mixed into points/text. */
+export type TextLabelRuntime = TextLabelState & TextLabelMethods;
+/** Operations shared by standalone text and attached point text. */
+export interface TextLabelMethods {
+    resetText(this: TextLabelRuntime): void;
+    freeText(this: TextLabelRuntime, tile: TextTile): void;
+    parseTextFeature(this: TextLabelRuntime, feature: TextFeature, draw: TextLabelDraw, context: TextContext, tile: TextTile): ParsedTextFeature | ParsedTextFeature[] | false | undefined;
+    parseTextSource(this: TextLabelRuntime, feature: TextFeature, draw: TextLabelDraw, context: TextContext): TextValue | Record<string, TextValue>;
+    parseTextSourceValue(this: TextLabelRuntime, source: TextSourceValue | TextSourceValue[], feature: TextFeature, context: TextContext): TextValue;
+    prepareTextLabels(this: TextLabelRuntime, tile: TextTile, queue: TextFeatureQueue[]): Promise<TextLabelCandidate[]>;
+    collideAndRenderTextLabels(this: TextLabelRuntime, tile: TextTile, group: string, queue: TextFeatureQueue[]): Promise<TextLabelResult>;
+    cullTextStyles(this: TextLabelRuntime, texts: TextTable, labels: TextLabelCandidate[]): void;
+    calcTextSizes(this: TextLabelRuntime, tileId: string, texts: TextTable): Promise<TextTable | undefined>;
+    rasterizeTexts(this: TextLabelRuntime, tileId: string, tileKey: string, texts: TextTable): Promise<TextLabelResult>;
+    preprocessText(this: TextLabelRuntime, draw: TextLabelDraw): TextLabelDraw | undefined;
+    computeTextLayout(this: TextLabelRuntime, target: Partial<LabelLayout>, feature: TextFeature, draw: TextLabelDraw, context: TextContext, tile: TextTile, text: TextValue, settings: TextSettingsResult, repeatGroup?: string, orientation?: string): LabelLayout;
+}
+/** Legacy broker boundary with explicit asynchronous payload types. */
+const typedWorkerBroker = WorkerBroker;
+/** Collision/rasterization may return no data after cancellation or teardown. */
+export interface TextLabelResult {
+    labels?: TextLabelCandidate[];
+    texts?: TextTable;
+    textures?: string[];
+}
+import Geo from '../../utils/geo';
+import log from '../../utils/log';
+import Thread from '../../utils/thread';
+import WorkerBroker from '../../utils/worker_broker';
+import Collision from '../../labels/collision';
+import TextSettings from '../text/text_settings';
+import TextCanvas from './text_canvas';
+
+// namespaces label textures (ensures new texture name when a tile is built multiple times)
+let text_texture_id = 0;
+
+export const TextLabels: TextLabelMethods = {
+
+    resetText (this: TextLabelRuntime): void {
+        if (Thread.is_main) {
+            this.canvas = new TextCanvas();
+        }
+        else if (Thread.is_worker) {
+            this.texts = {}; // unique texts, grouped by tile, by style
+        }
+    },
+
+    freeText (this: TextLabelRuntime, tile: TextTile): void {
+        delete this.texts[tile.id];
+    },
+
+    parseTextFeature (this: TextLabelRuntime, feature: TextFeature, draw: TextLabelDraw, context: TextContext, tile: TextTile): ParsedTextFeature | ParsedTextFeature[] | false | undefined {
+        // Compute label text
+        let text = this.parseTextSource(feature, draw, context);
+
+        if (text == null || text === '') {
+            return; // no text for this feature
+        }
+
+        // Compute text style and layout settings for this feature label
+        let text_settings = TextSettings.compute(draw, context);
+        let text_settings_key = TextSettings.key(text_settings);
+
+        // first label in tile, or with this style?
+        this.texts[tile.id] = this.texts[tile.id] || {};
+        let sizes = this.texts[tile.id][text_settings_key] = this.texts[tile.id][text_settings_key] || {};
+
+        if (text instanceof Object){
+            let results: ParsedTextFeature[] = [];
+
+            // add both left/right text elements to repeat group to improve repeat culling
+            // avoids one component of a boundary label (e.g. Colorado) being culled too aggressively when it also
+            // appears in nearby boundary labels (e.g. Colorado/Utah & Colorado/New Mexico repeat as separate groups)
+            let repeat_group_prefix = text.left + '-' + text.right; // NB: should be all text keys, not just left/right
+
+            for (let key in text){
+                let current_text = text[key];
+                if (!current_text) {
+                    continue;
+                }
+
+                let layout = this.computeTextLayout({}, feature, draw, context, tile, current_text, text_settings, repeat_group_prefix, key);
+                if (!sizes[current_text as string]) {
+                    // first label with this text/style/tile combination, make a new label entry
+                    sizes[current_text as string] = {
+                        text_settings,
+                        ref: 0 // # of times this text/style combo appears in tile
+                    };
+                }
+
+                results.push({
+                    draw, text : current_text as string, text_settings_key, layout
+                });
+            }
+
+            return (results.length > 0 && results); // return null if no boundary labels found
+        }
+        else {
+            // unique text strings, grouped by text drawing style
+            let layout = this.computeTextLayout({}, feature, draw, context, tile, text, text_settings);
+            if (!sizes[text as string]) {
+                // first label with this text/style/tile combination, make a new label entry
+                sizes[text as string] = {
+                    text_settings,
+                    ref: 0 // # of times this text/style combo appears in tile
+                };
+            }
+
+            return {
+                draw, text: text as string, text_settings_key, layout
+            };
+        }
+    },
+
+    // Compute the label text, default is value of feature.properties.name
+    // - String value indicates a feature property look-up, e.g. `short_name` means use feature.properties.short_name
+    // - Function will use the return value as the label text (for custom labels)
+    // - Array (of strings and/or functions) defines a list of fallbacks, evaluated according to the above rules,
+    //   with the first non-null value used as the label text
+    //   e.g. `[name:es, name:en, name]` prefers Spanish names, followed by English, and last the default local name
+    parseTextSource (this: TextLabelRuntime, feature: TextFeature, draw: TextLabelDraw, context: TextContext): TextValue | Record<string, TextValue> {
+        let text: TextValue | Record<string, TextValue>;
+        let source = draw.text_source || 'name';
+
+        if (source != null && !Array.isArray(source) && typeof source === 'object') {
+            // left/right boundary labels
+            text = {};
+            for (let key in source) {
+                text[key] = this.parseTextSourceValue(source[key], feature, context);
+            }
+        }
+        else {
+            // single label
+            text = this.parseTextSourceValue(source, feature, context);
+        }
+
+        return text;
+    },
+
+    parseTextSourceValue (this: TextLabelRuntime, source: TextSourceValue | TextSourceValue[], feature: TextFeature, context: TextContext): TextValue {
+        let text: TextValue;
+        if (Array.isArray(source)) {
+            for (let s=0; s < source.length; s++) {
+                if (typeof source[s] === 'string') {
+                    text = feature.properties[source[s] as string];
+                } else if (typeof source[s] === 'function') {
+                    text = (source[s] as (context: TextContext) => TextValue)(context);
+                }
+
+                if (text) {
+                    return text; // stop if we found a text property
+                }
+            }
+        }
+        else if (typeof source === 'string') {
+            text = feature.properties[source];
+        }
+        else if (source instanceof Function) {
+            text = source(context);
+        }
+
+        return text;
+    },
+
+    async prepareTextLabels (this: TextLabelRuntime, tile: TextTile, queue: TextFeatureQueue[]): Promise<TextLabelCandidate[]> {
+        if (Object.keys(this.texts[tile.id]||{}).length === 0) {
+            return [];
+        }
+
+        // first call to main thread, ask for text pixel sizes
+        try {
+            const texts = await typedWorkerBroker.postMessage<TextTable | undefined>(this.main_thread_target+'.calcTextSizes', tile.id, this.texts[tile.id]);
+            if (tile.canceled) {
+                log('trace', `Style ${this.name}: stop tile build because tile was canceled: ${tile.key}, post-calcTextSizes()`);
+                return [];
+            }
+
+            this.texts[tile.id] = texts || [] as unknown as TextTable;
+            if (!texts) {
+                Collision.abortTile(tile.id);
+                return [];
+            }
+
+            return this.buildTextLabels(tile, queue);
+        }
+        catch (e) { // error thrown if style has been removed from main thread
+            Collision.abortTile(tile.id);
+            return [];
+        }
+    },
+
+    async collideAndRenderTextLabels (this: TextLabelRuntime, tile: TextTile, collision_group: string, queue: TextFeatureQueue[]): Promise<TextLabelResult> {
+        let labels = await this.prepareTextLabels(tile, queue);
+        if (labels.length === 0) {
+            Collision.collide([], collision_group, tile.id);
+            return {};
+        }
+
+        labels = await Collision.collide(labels, collision_group, tile.id);
+        if (tile.canceled) {
+            log('trace', `stop tile build because tile was canceled: ${tile.key}, post-collide()`);
+            return {};
+        }
+
+        let texts = this.texts[tile.id];
+        if (texts == null || labels.length === 0) {
+            return {};
+        }
+
+        this.cullTextStyles(texts, labels);
+
+        // set alignments
+        labels.forEach(q => {
+            let text_settings_key = q.text_settings_key;
+            let text_info = texts[text_settings_key] && texts[text_settings_key][q.text];
+            if (!text_info.text_settings.can_articulate){
+                text_info.align = text_info.align || {};
+                text_info.align[q.label.align!] = {};
+            }
+            else {
+                // consider making it a set
+                if (!text_info.type) {
+                    text_info.type = [];
+                }
+
+                if (text_info.type.indexOf(q.label.type) === -1){
+                    text_info.type.push(q.label.type);
+                }
+            }
+        });
+
+        // second call to main thread, for rasterizing the set of texts
+        try {
+            const rasterized = await typedWorkerBroker.postMessage<TextLabelResult>(this.main_thread_target+'.rasterizeTexts', tile.id, tile.key, texts);
+            if (tile.canceled) {
+                log('trace', `stop tile build because tile was canceled: ${tile.key}, post-rasterizeTexts()`);
+                return {};
+            }
+            return { labels, ...rasterized };
+        }
+        catch (e) { // error thrown if style has been removed from main thread
+            return {};
+        }
+    },
+
+    // Remove unused text/style combinations to avoid unnecessary rasterization
+    cullTextStyles(this: TextLabelRuntime, texts: TextTable, labels: TextLabelCandidate[]): void {
+        // Count how many times each text/style combination is used
+        for (let i=0; i < labels.length; i++) {
+            let label = labels[i];
+            texts[label.text_settings_key][label.text].ref++;
+        }
+
+        // Remove text/style combinations that have no visible labels
+        for (let style in texts) {
+            for (let text in texts[style]) {
+                // no labels for this text
+                if (texts[style][text].ref < 1) {
+                    delete texts[style][text];
+                }
+            }
+        }
+
+        for (let style in texts) {
+            // no labels for this style
+            if (Object.keys(texts[style]).length === 0) {
+                delete texts[style];
+            }
+        }
+    },
+
+    // Called on main thread from worker, to compute the size of each text string,
+    // were it to be rendered. This info is then used to perform initial label culling, *before*
+    // labels are actually rendered.
+    calcTextSizes (this: TextLabelRuntime, tile_id: string, texts: TextTable): Promise<TextTable | undefined> {
+        return this.canvas.textSizes(tile_id, texts);
+    },
+
+    // Called on main thread from worker, to create atlas of labels for a tile
+    async rasterizeTexts (this: TextLabelRuntime, tile_id: string, tile_key: string, texts: TextTable): Promise<TextLabelResult> {
+        let canvas = new TextCanvas(); // one per style per tile (style may be rendering multiple tiles at once)
+        let max_texture_size = Math.min(this.max_texture_size, 2048); // cap each label texture at 2048x2048
+
+        let textures: TextAtlas[] | string[] | undefined = canvas.setTextureTextPositions(texts, max_texture_size);
+        let texture_prefix = ['labels', this.name, tile_key, tile_id, text_texture_id, ''].join('-');
+        text_texture_id++;
+
+        textures = await canvas.rasterize(
+            texts,
+            textures,
+            tile_id,
+            texture_prefix,
+            this.resource_context
+        );
+        if (!textures) {
+            return {};
+        }
+        return { texts, textures };
+    },
+
+    preprocessText (this: TextLabelRuntime, draw: TextLabelDraw): TextLabelDraw | undefined {
+        // Font settings are required
+        if (!draw || !draw.font || typeof draw.font !== 'object') {
+            return;
+        }
+
+        // Font weight
+        draw.font.weight = typedStyleParser.createPropertyCache(draw.font.weight);
+
+        // Colors
+        draw.font.fill = typedStyleParser.createPropertyCache(draw.font.fill || TextSettings.defaults.fill);
+        draw.font.alpha = typedStyleParser.createPropertyCache(draw.font.alpha);
+
+        if (draw.font.stroke) {
+            draw.font.stroke.color = typedStyleParser.createPropertyCache(draw.font.stroke.color);
+            draw.font.stroke.alpha = typedStyleParser.createPropertyCache(draw.font.stroke.alpha);
+        }
+
+        if (draw.font.background) {
+            draw.font.background.color = typedStyleParser.createPropertyCache(draw.font.background.color);
+            draw.font.background.alpha = typedStyleParser.createPropertyCache(draw.font.background.alpha);
+            draw.font.background.width = typedStyleParser.createPropertyCache(draw.font.background.width, typedStyleParser.parsePositiveNumber);
+            if (draw.font.background.stroke) {
+                draw.font.background.stroke.color = typedStyleParser.createPropertyCache(draw.font.background.stroke.color);
+                draw.font.background.stroke.alpha = typedStyleParser.createPropertyCache(draw.font.background.stroke.alpha);
+            }
+        }
+
+        // Convert font and text stroke sizes
+        draw.font.px_size = typedStyleParser.createPropertyCache(draw.font.size || TextSettings.defaults.size, TextCanvas.fontPixelSize, TextCanvas.fontPixelSize);
+
+        if (draw.font.stroke && draw.font.stroke.width != null) {
+            draw.font.stroke.width = typedStyleParser.createPropertyCache(draw.font.stroke.width, typedStyleParser.parsePositiveNumber);
+        }
+
+        if (draw.font.background && draw.font.background.stroke && draw.font.background.stroke.width != null) {
+            draw.font.background.stroke.width = typedStyleParser.createPropertyCache(draw.font.background.stroke.width, typedStyleParser.parsePositiveNumber);
+        }
+
+        // Offset (2d array)
+        draw.offset = typedStyleParser.createPropertyCache(draw.offset,
+            v => Array.isArray(v) && v.map(typedStyleParser.parseNumber)
+        );
+
+        // Buffer (1d value or or 2d array) - must be >= 0
+        draw.buffer = typedStyleParser.createPropertyCache(draw.buffer,
+            v => (Array.isArray(v) ? v : [v, v]).map(typedStyleParser.parsePositiveNumber)
+        );
+
+        // Repeat rules - for text labels, defaults to tile size
+        draw.repeat_distance = typedStyleParser.createPropertyCache(
+            draw.repeat_distance,
+            typedStyleParser.parsePositiveNumber
+        );
+
+        return draw;
+    },
+
+    // Additional text-specific layout settings
+    computeTextLayout (this: TextLabelRuntime, target: Partial<LabelLayout>, feature: TextFeature, draw: TextLabelDraw, context: TextContext, tile: TextTile, text: TextValue, text_settings: TextSettingsResult, repeat_group_prefix?: string, orientation?: string): LabelLayout {
+        let layout: Partial<LabelLayout> = target || {};
+
+        // common settings w/points
+        layout = this.computeLayout(layout, feature, draw, context, tile);
+
+        // if draw group didn't specify repeat distance, override with text label-specific logic
+        if (draw.repeat_distance == null) {
+            // defaults: no limit on labels for point geometries,  tile size (256px) limit for other geometries
+            layout.repeat_distance = (context.geometry === 'point' ? 0 : Geo.tile_size);
+
+            if (layout.repeat_distance) {
+                layout.repeat_distance *= layout.units_per_pixel!;
+                layout.repeat_scale = 1; // initial repeat pass in tile with full scale
+
+                if (typeof draw.repeat_group === 'function') {
+                    layout.repeat_group = draw.repeat_group(context); // dynamic repeat group
+                }
+                else {
+                    layout.repeat_group = draw.repeat_group; // pre-computed repeat group
+                }
+            }
+        }
+
+        // repeat rules include the text
+        if (layout.repeat_distance) {
+            if (repeat_group_prefix) {
+                layout.repeat_group += '/' + repeat_group_prefix;
+            }
+            layout.repeat_group += '/' + text;
+        }
+
+        // Max number of subdivisions to try
+        if (this.screen_space_labels || this.cpu_projection) {
+            // Preserve text identity even without IDs; position matching prevents unrelated names collapsing.
+            layout.projected_identity = JSON.stringify([layout.projected_identity ?? [context.source, context.layer,
+                this.name, draw.key], String(text)]);
+        }
+        layout.subdiv = tile.overzoom2;
+
+        layout.align = draw.align;
+
+        // used to fudge width value as text may overflow bounding box if it has italic, bold, etc style
+        // TODO rename to more generic, not italic-specific (bold)
+        layout.italic = (text_settings.style !== 'normal');
+
+        // used to determine orientation of text if the text_source has a `left` or `right` key
+        if (orientation === 'right') {
+            layout.orientation = 1;
+        }
+        else if (orientation === 'left'){
+            layout.orientation = -1;
+        }
+
+        return layout as LabelLayout;
+    }
+
+};

package/src/styles/text/text_segments.ts

@@ -0,0 +1,142 @@
+// Tangram
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2013-2016 Brett Camper and Mapzen
+
+// Text directionality (right-to-left, bi-directional) and segmentation (curved labels, Arabic handling)
+
+// Right-to-left / bi-directional text handling
+// Taken from http://stackoverflow.com/questions/12006095/javascript-how-to-check-if-character-is-rtl
+
+type SegmentCache = {
+    segment: Record<string, string[]>;
+    stats: {
+        segment_hits: number;
+        segment_misses: number;
+    };
+};
+
+const rtl_test = new RegExp('[\u0591-\u07FF\u200F\u202B\u202E\uFB1D-\uFDFD\uFE70-\uFEFC]');
+export function isTextRTL(s: string): boolean {
+    return rtl_test.test(s);
+}
+
+const neutral_chars = '\u0000-\u002F\u003A-\u0040\u005B-\u0060\u007B-\u00BF\u00D7\u00F7\u02B9-\u02FF\u2000-\u2BFF\u2010-\u2029\u202C\u202F-\u2BFF';
+const neutral_test = new RegExp('['+neutral_chars+']+');
+export function isTextNeutral(s: string): boolean {
+    return neutral_test.test(s);
+}
+
+export const RTL_MARKER = '\u200F'; // explicit right-to-left marker
+
+// Arabic script ranges
+// test http://localhost:8000/#16.72917/30.08541/31.28466
+const arabic_range = new RegExp('^['+neutral_chars+'\u0600-\u06FF]+'); // all characters are Arabic or neutral
+const arabic_splitters = new RegExp('['+neutral_chars+'\u0622-\u0625\u0627\u062F-\u0632\u0648\u0671-\u0677\u0688-\u0699\u06C4-\u06CB\u06CF\u06D2\u06D3\u06EE\u06EF]');
+const arabic_vowels = new RegExp('^[\u0610-\u061A\u064B-\u065F\u0670\u06D6-\u06DC\u06DF-\u06E4\u06E7\u06E8\u06EA-\u06ED]+');
+
+// Complex script ranges (non-Arabic)
+const accents_and_vowels = '[\u0300-\u036F' + // Combining Diacritical Marks
+'\u0591-\u05BD\u05BF\u05C1\u05C2\u05C4\u05C5\u05C7' + // Hebrew
+'\u07A6-\u07B0' + // Thaana
+'\u0900-\u0903\u093A-\u094C\u094E\u094F\u0951-\u0957\u0962\u0963' + // Devanagari
+'\u0981-\u0983\u09BC\u09BE-\u09CC\u09D7\u09E2\u09E3' + // Bengali
+'\u0A01-\u0A03\u0A3C-\u0A4C\u0A51' + // Gurmukhi
+'\u0A81-\u0A83\u0ABC\u0ABE-\u0ACC\u0AE2\u0AE3' + // Gujarati
+'\u0B01-\u0B03\u0B3C\u0B3E-\u0B4C\u0B56\u0B57\u0B62\u0B63' + // Oriya
+'\u0B82\u0BBE-\u0BCD\u0BD7' + // Tamil
+'\u0C00-\u0C03\u0C3E-\u0C4C\u0C55\u0C56\u0C62\u0C63' + // Telugu
+'\u0C81-\u0C83\u0CBC\u0CBE-\u0CCC\u0CD5\u0CD6\u0CE2\u0CE3' + // Kannada
+'\u0D01-\u0D03\u0D3E-\u0D4C\u0D4E\u0D57\u0D62\u0D63' + // Malayalam
+'\u0D82\u0D83\u0DCA-\u0DDF\u0DF2\u0DF3' + // Sinhala
+'\u0E31\u0E34-\u0E3A\u0E47-\u0E4E' + // Thai
+'\u0EB1\u0EB4-\u0EBC\u0EC8-\u0ECD' + // Lao
+'\u0F18\u0F19\u0F35\u0F37\u0F39\u0F3E\u0F3F\u0F71-\u0F83\u0F86\u0F87\u0F8D-\u0FBC\u0FC6' + // Tibetan
+'\u102B-\u1038\u103A-\u103E\u1056-\u1059\u105E-\u1060\u1062-\u1064\u1067-\u106D\u1071-\u1074\u1082-\u108D\u108F\u109A-\u109D' + // Burmese
+'\u17B4-\u17D1\u17D3' + // Khmer
+'\u1A55-\u1A5E\u1A61-\u1A7C' + // Tai Tham
+'\u1DC0-\u1DFF' + // Combining Diacritical Marks Supplement
+'\u20D0-\u20FF' + // Combining Diacritical Marks for Symbols
+']';
+const combo_characters = '[\u094D\u09CD\u0A4D\u0ACD\u0B4D\u0C4D\u0CCD\u0D4D\u0F84\u1039\u17D2\u1A60\u1A7F]';
+
+// Find the next grapheme cluster (non-Arabic)
+const grapheme_match = new RegExp(`^.(?:${accents_and_vowels}+)?(${combo_characters}\\W(?:${accents_and_vowels}+)?)*`); // eslint-disable-line no-misleading-character-class
+
+// Scripts that cannot be curved due (due to contextual shaping and/or layout complexity)
+const curve_blacklist: Record<string, string> = {
+    Mongolian: '\u1800-\u18AF'
+};
+const curve_blacklist_range = Object.keys(curve_blacklist).map(r => curve_blacklist[r]).join('');
+const curve_blacklist_test = new RegExp('['+curve_blacklist_range+']');
+export function isTextCurveBlacklisted(s: string): boolean {
+    return curve_blacklist_test.test(s);
+}
+
+// Splitting strategy for chopping a label into segments
+const default_segment_length = 2; // character length of each segment when dividing up label text
+
+export function splitLabelText(text: string, rtl: boolean, cache: SegmentCache): string[] {
+    // Use single-character segments for RTL, to avoid additional handling for neutral characters
+    // (see https://github.com/tangrams/tangram/issues/541)
+    const segment_length = rtl ? 1 : default_segment_length;
+
+    // Only one segment
+    if (text.length < segment_length) {
+        return [text];
+    }
+
+    // Check segment cache first (skips processing for labels we've seen before)
+    let key = text;
+    if (cache.segment[key]) {
+        cache.stats.segment_hits++;
+        return cache.segment[key];
+    }
+
+    let segments: string[] = [];
+
+    // Arabic-specific text handling
+    // NB: works for strings that are *only* Arabic; mixed-script labels may need more work
+    if (arabic_range.exec(text)) {
+        segments = text.split(arabic_splitters);
+        let offset = -1;
+        for (var s = 0; s < segments.length - 1; s++) {
+            if (s > 0) {
+                let carryover_vowels = arabic_vowels.exec(segments[s]);
+                if (carryover_vowels) {
+                    segments[s] = segments[s].substring(carryover_vowels[0].length);
+                    segments[s - 1] += carryover_vowels[0];
+                    offset += carryover_vowels[0].length;
+                }
+            }
+            offset += 1 + segments[s].length;
+            segments[s] += text.slice(offset, offset + 1);
+        }
+        text = ''; // will skip non-Arabic handling below
+    }
+
+    // Non-Arabic text handling
+    while (text.length) {
+        let segment = '';
+        let test_text = text;
+        let grapheme_count = 0;
+
+        for (grapheme_count; grapheme_count < segment_length && test_text.length; grapheme_count++) {
+            let grapheme_cluster = (grapheme_match.exec(test_text) || test_text)[0];
+            segment += grapheme_cluster;
+            test_text = test_text.substring(grapheme_cluster.length);
+        }
+
+        segments.push(segment);
+        text = text.substring(segment.length);
+    }
+
+    // Reverse segments if needed
+    if (rtl) {
+        segments.reverse();
+    }
+
+    // Cache and return
+    cache.stats.segment_misses++;
+    cache.segment[key] = segments;
+    return segments;
+}