@readium/helpers 1.0.0 → 1.1.0

package/types/src/index.d.ts

@@ -1,2 +1,5 @@
 export * from "./color.ts";
 export * from "./sML.ts";
+export * from "./textFragmentDirective.ts";
+export * from "./vendor/text-fragments-polyfill/textFragmentMatcher.ts";
+export * from "./vendor/text-fragments-polyfill/textFragmentGenerator.ts";

package/types/src/textFragmentDirective.d.ts

@@ -0,0 +1,7 @@
+export interface TextFragmentDirective {
+    textStart: string;
+    textEnd?: string;
+    prefix?: string;
+    suffix?: string;
+}
+export declare function decodeTextFragmentDirective(textref: string | undefined): TextFragmentDirective | undefined;

package/types/src/vendor/text-fragments-polyfill/textFragmentGenerator.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Copyright 2020 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import type { TextFragment } from './textFragmentMatcher.ts';
+/**
+ * Allows overriding the max runtime to specify a different interval. Fragment
+ * generation will halt and throw an error after this amount of time.
+ * @param newTimeoutDurationMs - the desired timeout length, in ms.
+ */
+export declare const setFragmentGenerationTimeout: (newTimeoutDurationMs: number | null) => void;
+/**
+ * Enum indicating the success, or failure reason, of generateFragment.
+ */
+export declare const GenerateFragmentStatus: {
+    readonly SUCCESS: 0;
+    readonly INVALID_SELECTION: 1;
+    readonly AMBIGUOUS: 2;
+    readonly TIMEOUT: 3;
+    readonly EXECUTION_FAILED: 4;
+};
+export type GenerateFragmentStatusValue = typeof GenerateFragmentStatus[keyof typeof GenerateFragmentStatus];
+export interface GenerateFragmentResult {
+    status: GenerateFragmentStatusValue;
+    fragment?: TextFragment;
+}
+/**
+ * Attempts to generate a fragment, suitable for formatting and including in a
+ * URL, which will highlight the given selection upon opening.
+ * @param selection - a Selection object, the result of window.getSelection
+ * @param startTime - the time when generation began, for timeout purposes.
+ *     Defaults to current timestamp.
+ */
+export declare const generateFragment: (selection: Selection, startTime?: number) => GenerateFragmentResult;
+/**
+ * Attampts to generate a fragment using a given range. @see {@link generateFragment}
+ * @param startTime - the time when generation began, for timeout purposes.
+ *     Defaults to current timestamp.
+ */
+export declare const generateFragmentFromRange: (range: Range, startTime?: number) => GenerateFragmentResult;
+/**
+ * Checks whether fragment generation can be attempted for a given range. This
+ * checks a handful of simple conditions: the range must be nonempty, not inside
+ * an <input>, etc. A true return is not a guarantee that fragment generation
+ * will succeed; instead, this is a way to quickly rule out generation in cases
+ * where a failure is predictable.
+ * @return true if fragment generation may proceed; false otherwise.
+ */
+export declare const isValidRangeForFragmentGeneration: (range: Range) => boolean;

package/types/src/vendor/text-fragments-polyfill/textFragmentMatcher.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Copyright 2020 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+export interface TextFragment {
+    textStart: string;
+    textEnd?: string;
+    prefix?: string;
+    suffix?: string;
+}
+interface BoundaryPoint {
+    node: Node;
+    offset: number;
+}
+/**
+ * Searches the document for a given text fragment.
+ *
+ * @param textFragment - Text Fragment to highlight.
+ * @param documentToProcess - document where to extract and mark fragments in.
+ * @param root - the root element where to extract and mark fragments in.
+ * @return Zero or more ranges within the document corresponding to the
+ *     fragment. If the fragment corresponds to more than one location in the
+ *     document (i.e., is ambiguous) then the first two matches will be
+ *     returned (regardless of how many more matches there may be in the
+ *     document).
+ */
+export declare const processTextFragmentDirective: (textFragment: TextFragment, documentToProcess: Document, root?: Node) => Range[];
+/**
+ * Should not be referenced except in the /test directory.
+ */
+export declare const forTesting: {
+    advanceRangeStartPastOffset: (range: Range, node: Node, offset: number) => void;
+    advanceRangeStartToNonWhitespace: (range: Range) => void;
+    findRangeFromNodeList: (query: string, range: Range, textNodes: Text[], segmenter?: Intl.Segmenter) => Range | undefined;
+    findTextInRange: (query: string, range: Range) => Range | undefined;
+    getBoundaryPointAtIndex: (index: number, textNodes: Text[], isEnd: boolean) => BoundaryPoint | undefined;
+    isWordBounded: (text: string, startPos: number, length: number, segmenter?: Intl.Segmenter) => boolean;
+    makeNewSegmenter: (doc?: Document) => Intl.Segmenter | undefined;
+    normalizeString: (str?: string) => string;
+    forwardTraverse: (walker: TreeWalker, finishedSubtrees: Set<Node>) => Node | null;
+    backwardTraverse: (walker: TreeWalker, finishedSubtrees: Set<Node>) => Node | null;
+    getAllTextNodes: (root: Node, range?: Range) => Text[][];
+    acceptTextNodeIfVisibleInRange: (node: Node, range?: Range) => number;
+};
+/**
+ * Should only be used by other files in this directory.
+ */
+export declare const internal: {
+    BLOCK_ELEMENTS: string[];
+    BOUNDARY_CHARS: RegExp;
+    NON_BOUNDARY_CHARS: RegExp;
+    acceptNodeIfVisibleInRange: (node: Node, range?: Range) => number;
+    normalizeString: (str?: string) => string;
+    makeNewSegmenter: (doc?: Document) => Intl.Segmenter | undefined;
+    forwardTraverse: (walker: TreeWalker, finishedSubtrees: Set<Node>) => Node | null;
+    backwardTraverse: (walker: TreeWalker, finishedSubtrees: Set<Node>) => Node | null;
+    makeTextNodeWalker: (range: Range) => TreeWalker;
+    isNodeVisible: (node: Node) => boolean;
+};
+export {};