kennzeichen 0.1.0

package/README.md

@@ -0,0 +1,234 @@
+# kennzeichen
+
+German license plate parsing and validation. Framework-agnostic core with React adapter.
+
+## Installation
+
+```bash
+npm install kennzeichen
+```
+
+## Features
+
+- Parse German license plates with ambiguity detection
+- 726 valid location codes (Unterscheidungszeichen)
+- Handles E (electric) and H (historic) suffixes
+- Framework-agnostic core
+- React hook + headless component
+
+## Usage
+
+### Core (any environment)
+
+The core module works in any JavaScript environment (Node.js, browser, Deno, etc.).
+
+```typescript
+import {
+  parseLicensePlate,
+  formatParsedPlate,
+  isValidLicensePlate,
+  sanitizeLicensePlate,
+  LOCATION,
+} from "kennzeichen";
+
+// Parse a license plate
+const result = parseLicensePlate("M-AB 1234");
+// { type: 'unambiguous', plate: { part1: 'M', part2: 'AB', part3: '1234' } }
+
+// Handle ambiguous input (no separator)
+const ambiguous = parseLicensePlate("CEE1234");
+// { type: 'ambiguous', options: [
+//   { part1: 'C', part2: 'EE', part3: '1234' },
+//   { part1: 'CE', part2: 'E', part3: '1234' }
+// ] }
+
+// Format a parsed plate
+formatParsedPlate({ part1: "M", part2: "AB", part3: "1234" });
+// 'M-AB 1234'
+
+// Validate
+isValidLicensePlate("M-AB 1234"); // true
+isValidLicensePlate("XX-AB 1234"); // false (invalid location)
+
+// Sanitize (remove separators)
+sanitizeLicensePlate("M-AB 1234"); // 'MAB1234'
+
+// Check if a location code exists
+LOCATION.includes("M"); // true
+LOCATION.includes("XX"); // false
+```
+
+### Parse Result Types
+
+```typescript
+type ParseResult =
+  | { type: "unambiguous"; plate: ParsedPlate } // Single valid interpretation
+  | { type: "ambiguous"; options: ParsedPlate[] } // Multiple valid interpretations
+  | { type: "partial"; plate: Partial<ParsedPlate> } // Incomplete but valid so far
+  | { type: "invalid" }; // Cannot be parsed
+
+type ParsedPlate = {
+  part1: string; // Location code (e.g., 'M', 'HH', 'BGL')
+  part2: string; // Letters (e.g., 'AB', 'X')
+  part3: string; // Numbers + optional suffix (e.g., '1234', '99E', '42H')
+};
+```
+
+### React Hook
+
+The hook provides full control over the input state and disambiguation logic.
+
+```tsx
+import { useLicensePlate, formatParsedPlate } from "kennzeichen/react";
+
+function MyLicensePlateInput({ value, onChange }) {
+  const lp = useLicensePlate({ value, onChange });
+
+  return (
+    <div className="relative">
+      <input
+        value={lp.inputValue}
+        onChange={lp.handleChange}
+        onKeyDown={lp.handleKeyDown}
+        onBlur={lp.handleBlur}
+        placeholder="z.B. M-AB 1234"
+      />
+      {lp.isDropdownOpen && lp.options && (
+        <ul className="absolute mt-1 border rounded bg-white shadow-lg">
+          {lp.options.map((opt, i) => (
+            <li
+              key={i}
+              className={`px-3 py-2 cursor-pointer ${
+                i === lp.activeIndex ? "bg-blue-100" : "hover:bg-gray-100"
+              }`}
+              onMouseEnter={() => lp.setActiveIndex(i)}
+              onMouseDown={(e) => e.preventDefault()}
+              onClick={() => lp.selectOption(opt)}
+            >
+              {formatParsedPlate(opt)}
+            </li>
+          ))}
+        </ul>
+      )}
+    </div>
+  );
+}
+```
+
+### React Headless Component
+
+The headless component uses render props to reduce boilerplate while still giving you full control over the UI.
+
+```tsx
+import { LicensePlateInput } from "kennzeichen/react";
+
+function MyLicensePlateInput({ value, onChange }) {
+  return (
+    <LicensePlateInput value={value} onChange={onChange}>
+      {({ inputProps, isOpen, options }) => (
+        <div className="relative">
+          <input
+            {...inputProps}
+            className="border rounded px-3 py-2 w-full"
+            placeholder="z.B. M-AB 1234"
+          />
+          {isOpen && options && (
+            <ul className="absolute mt-1 border rounded bg-white shadow-lg w-full">
+              {options.map((opt) => (
+                <li
+                  key={opt.formatted}
+                  className={`px-3 py-2 cursor-pointer ${
+                    opt.isActive ? "bg-blue-100" : "hover:bg-gray-100"
+                  }`}
+                  {...opt.getProps()}
+                >
+                  {opt.formatted}
+                </li>
+              ))}
+            </ul>
+          )}
+        </div>
+      )}
+    </LicensePlateInput>
+  );
+}
+```
+
+## API Reference
+
+### Core
+
+#### `parseLicensePlate(input: string): ParseResult`
+
+Parses a license plate input string into its component parts. Handles various input formats:
+
+- With hyphen: `"M-AB 1234"`
+- With spaces: `"M AB 1234"`
+- Without separators: `"MAB1234"`
+
+#### `formatParsedPlate(plate: Partial<ParsedPlate>): string`
+
+Formats a parsed plate into the standard display format: `"M-AB 1234"`.
+
+#### `isValidLicensePlate(input: string): boolean`
+
+Returns `true` if the input can be unambiguously parsed as a valid German license plate.
+
+#### `sanitizeLicensePlate(plate: string): string`
+
+Removes all spaces and hyphens from a license plate string.
+
+#### `LOCATION: string[]`
+
+Array of all 726 valid German location codes.
+
+#### `LOCATION_SET: Set<string>`
+
+Set of all valid location codes for O(1) lookup.
+
+### React
+
+#### `useLicensePlate(options): UseLicensePlateReturn`
+
+React hook for managing license plate input state.
+
+**Options:**
+
+- `value?: string` - Controlled value
+- `onChange?: (value: string) => void` - Called when value changes
+- `onBlur?: () => void` - Called when input loses focus
+
+**Returns:**
+
+- `inputValue: string` - Current input value
+- `parseResult: ParseResult` - Current parse result
+- `handleChange` - Input onChange handler
+- `handleKeyDown` - Input onKeyDown handler (for dropdown navigation)
+- `handleBlur` - Input onBlur handler
+- `isDropdownOpen: boolean` - Whether dropdown should be visible
+- `options: ParsedPlate[] | null` - Disambiguation options
+- `activeIndex: number` - Currently highlighted option
+- `selectOption(option)` - Select a disambiguation option
+- `setActiveIndex(index)` - Set highlighted option
+
+#### `<LicensePlateInput>` (Headless Component)
+
+Render props component for license plate input.
+
+**Props:**
+
+- `value?: string` - Controlled value
+- `onChange?: (value: string) => void` - Called when value changes
+- `onBlur?: () => void` - Called when input loses focus
+- `children: (props: RenderProps) => ReactNode` - Render function
+
+**RenderProps:**
+
+- `inputProps` - Props to spread on input element
+- `isOpen: boolean` - Whether dropdown should be visible
+- `options: OptionItem[] | null` - Disambiguation options with helper methods
+- `parseResult: ParseResult` - Current parse result
+
+## License
+
+MIT