@react-hive/honey-css 1.0.0 → 1.1.0

package/dist/create-css-token-cursor.d.ts

@@ -0,0 +1,132 @@
+import type { HoneyCssToken, HoneyCssTokenType } from '~/types';
+/**
+ * A lightweight cursor abstraction over a token stream.
+ *
+ * This is the core navigation primitive used by the Honey CSS parser.
+ * It provides safe sequential reading, lookahead, backtracking,
+ * and small helper utilities for collecting selector/value text.
+ */
+export interface HoneyTokenCursor {
+    /**
+     * Returns `true` when the cursor has consumed all tokens.
+     */
+    isEof: () => boolean;
+    /**
+     * Returns the current token without consuming it.
+     *
+     * This is primarily used for lookahead decisions in the parser:
+     *
+     * ```ts
+     * if (cursor.peek()?.type === 'braceOpen') {
+     *   // parse rule block
+     * }
+     * ```
+     */
+    peek: () => HoneyCssToken | undefined;
+    /**
+     * Consumes and returns the current token, advancing the cursor forward.
+     *
+     * Returns `undefined` if the cursor is already at EOF.
+     *
+     * ```ts
+     * const token = cursor.next();
+     * ```
+     */
+    next: () => HoneyCssToken | undefined;
+    /**
+     * Creates a checkpoint of the current cursor position.
+     *
+     * Useful for speculative parsing or backtracking:
+     *
+     * ```ts
+     * const mark = cursor.mark();
+     *
+     * if (!tryParseSomething(cursor)) {
+     *   cursor.reset(mark);
+     * }
+     * ```
+     */
+    mark: () => number;
+    /**
+     * Restores the cursor back to a previously created mark.
+     *
+     * @param mark - Index returned from {@link mark}.
+     */
+    reset: (mark: number) => void;
+    /**
+     * Consumes the next token and asserts that it matches the expected type.
+     *
+     * This is the parser's main safety mechanism and helps produce
+     * clear error messages during invalid input.
+     *
+     * Throws if:
+     * - the token stream ends unexpectedly
+     * - the next token has a different type
+     *
+     * ```ts
+     * cursor.expect('braceOpen'); // must be "{"
+     * ```
+     *
+     * @param type - Expected token type.
+     *
+     * @returns The consumed token, narrowed to the expected type.
+     */
+    expect: <T extends HoneyCssTokenType>(type: T) => Extract<HoneyCssToken, {
+        type: T;
+    }>;
+    /**
+     * Reads and concatenates consecutive token values until one of the stop token
+     * types is encountered.
+     *
+     * This helper is used to collect:
+     * - selectors (`.btn:hover`)
+     * - declaration values (`calc(100% - 1px)`)
+     * - at-rule names (`media`)
+     *
+     * Stops **before consuming** the stop token.
+     *
+     * Supported token types:
+     * - `text`   → appended as-is
+     * - `string` → wrapped in quotes
+     * - `params` → appended verbatim including parentheses
+     *
+     * Example:
+     *
+     * Tokens:
+     * ```
+     * text("var")
+     * params("(--color)")
+     * ```
+     *
+     * Result:
+     * ```
+     * "var(--color)"
+     * ```
+     *
+     * @param stopTypes - Token types that terminate reading.
+     *
+     * @returns Combined string value.
+     */
+    readUntil: (stopTypes: HoneyCssTokenType[]) => string;
+    /**
+     * Advances the cursor until one of the stop token types is reached.
+     *
+     * This is useful for error recovery and safely skipping unknown syntax.
+     *
+     * Stops before consuming the stop token.
+     *
+     * @param stopTypes - Token types that terminate skipping.
+     */
+    skipUntil: (stopTypes: HoneyCssTokenType[]) => void;
+}
+/**
+ * Creates a cursor wrapper around a list of CSS tokens.
+ *
+ * The cursor provides a small API surface for building
+ * recursive-descent parsers without needing complex parser generators.
+ *
+ * @param tokens - Token list produced by the Honey tokenizer.
+ *
+ * @returns A reusable cursor instance.
+ */
+export declare const createCssTokenCursor: (tokens: HoneyCssToken[]) => HoneyTokenCursor;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@react-hive/honey-css",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "A lightweight CSS tokenizer and parser that produces a simple AST for custom CSS processing.",
   "keywords": [
     "css",
@@ -47,20 +47,23 @@
   "engines": {
     "node": ">=18"
   },
+  "dependencies": {
+    "@react-hive/honey-utils": "3.23.0"
+  },
   "devDependencies": {
-    "@eslint/js": "9.39.1",
+    "@eslint/js": "9.39.2",
     "@mdx-js/loader": "3.1.1",
     "@types/jest": "29.5.14",
-    "@types/node": "22.19.1",
+    "@types/node": "22.19.11",
     "copy-webpack-plugin": "13.0.1",
-    "eslint": "9.39.1",
+    "eslint": "9.39.2",
     "eslint-plugin-react": "7.37.5",
     "jest": "29.7.0",
-    "prettier": "3.6.2",
-    "ts-jest": "29.4.4",
+    "prettier": "3.8.1",
+    "ts-jest": "29.4.6",
     "ts-loader": "9.5.4",
     "typescript": "5.9.3",
-    "typescript-eslint": "8.47.0",
+    "typescript-eslint": "8.55.0",
     "webpack": "5.105.2",
     "webpack-cli": "6.0.1"
   },