kennzeichen 0.1.3 → 0.1.4

package/README.md

@@ -18,38 +18,28 @@ npm install kennzeichen
 
 ## Usage
 
-### Core
-
-```typescript
-import { parseLicensePlate, isValidLicensePlate } from "kennzeichen";
-
-// Parse a license plate
-parseLicensePlate("M-AB 1234");
-// { type: 'unambiguous', plate: { part1: 'M', part2: 'AB', part3: '1234' } }
-
-// Ambiguous input returns multiple options
-parseLicensePlate("CEE1234");
-// { type: 'ambiguous', options: [...] }
-
-// Validate
-isValidLicensePlate("M-AB 1234"); // true
-isValidLicensePlate("XX-AB 1234"); // false
-```
-
-### Parse Result Types
+### React Headless Component
 
-```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
+```tsx
+import { LicensePlateInput } from "kennzeichen/react";
 
-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')
-};
+function MyInput({ value, onChange }) {
+  return (
+    <LicensePlateInput value={value} onChange={onChange}>
+      {({ inputProps, isOpen, options }) => (
+        <div>
+          <input {...inputProps} />
+          {isOpen &&
+            options?.map((opt) => (
+              <button key={opt.formatted} {...opt.getProps()}>
+                {opt.formatted}
+              </button>
+            ))}
+        </div>
+      )}
+    </LicensePlateInput>
+  );
+}
 ```
 
 ### React Hook
@@ -75,28 +65,77 @@ function LicensePlateInput({ value, onChange }) {
 }
 ```
 
-### React Headless Component
+### Vanilla HTML + JavaScript
 
-```tsx
-import { LicensePlateInput } from "kennzeichen/react";
+Use via CDN - no build step required:
 
-function MyInput({ value, onChange }) {
-  return (
-    <LicensePlateInput value={value} onChange={onChange}>
-      {({ inputProps, isOpen, options }) => (
-        <div>
-          <input {...inputProps} />
-          {isOpen &&
-            options?.map((opt) => (
-              <button key={opt.formatted} {...opt.getProps()}>
-                {opt.formatted}
-              </button>
-            ))}
-        </div>
-      )}
-    </LicensePlateInput>
-  );
+```html
+<input type="text" id="plate-input" placeholder="Enter license plate...">
+<div id="result"></div>
+
+<script type="module" src="app.js"></script>
+```
+
+```js
+// app.js
+import { parseLicensePlate, formatParsedPlate } from 
+  "https://cdn.jsdelivr.net/npm/kennzeichen/+esm"
+
+const input = document.getElementById("plate-input")
+const result = document.getElementById("result")
+
+input.addEventListener("input", (e) => {
+  const parsed = parseLicensePlate(e.target.value)
+  
+  if (parsed.type === "unambiguous") {
+    result.textContent = formatParsedPlate(parsed.plate)
+  } else if (parsed.type === "ambiguous") {
+    result.textContent = "Did you mean: " + 
+      parsed.options.map(formatParsedPlate).join(" or ")
+  } else if (parsed.type === "invalid") {
+    result.textContent = "Invalid plate"
+  }
+})
+```
+
+### Core API
+
+```typescript
+import { parseLicensePlate } from "kennzeichen"
+
+const result = parseLicensePlate("M-AB 1234")
+
+if (result.type === "unambiguous") {
+  console.log(result.plate)
+  // { part1: "M", part2: "AB", part3: "1234" }
+}
+
+if (result.type === "ambiguous") {
+  // User needs to pick one
+  console.log(result.options)
 }
+
+if (result.type === "invalid") {
+  // Not a valid German license plate
+}
+```
+
+#### Validate
+
+```typescript
+import { isValidLicensePlate } from "kennzeichen"
+
+isValidLicensePlate("M-AB 1234")   // true
+isValidLicensePlate("XX-AB 1234")  // false (invalid location)
+```
+
+#### Format
+
+```typescript
+import { formatParsedPlate } from "kennzeichen"
+
+formatParsedPlate({ part1: "M", part2: "AB", part3: "1234" })
+// "M-AB 1234"
 ```
 
 ## API Reference
@@ -105,19 +144,15 @@ function MyInput({ value, onChange }) {
 
 #### `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"`
+Parses a license plate input string. Handles various formats: `"M-AB 1234"`, `"M AB 1234"`, `"MAB1234"`.
 
 #### `formatParsedPlate(plate: Partial<ParsedPlate>): string`
 
-Formats a parsed plate into the standard display format: `"M-AB 1234"`.
+Formats a parsed plate into 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.
+Returns `true` if the input is a valid, unambiguous German license plate.
 
 #### `sanitizeLicensePlate(plate: string): string`
 
@@ -127,52 +162,52 @@ Removes all spaces and hyphens from a license plate string.
 
 Array of all 726 valid German location codes.
 
-#### `LOCATION_SET: Set<string>`
+### React
 
-Set of all valid location codes for O(1) lookup.
+#### `<LicensePlateInput>` (Headless Component)
 
-### React
+Render props component for license plate input.
+
+**Props:**
+- `value?: string` - Controlled value
+- `onChange?: (value: string) => void` - Called when value changes
+- `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
 
 #### `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:**
+### Types
 
-- `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:**
+```typescript
+type ParseResult =
+  | { type: "unambiguous"; plate: ParsedPlate }
+  | { type: "ambiguous"; options: ParsedPlate[] }
+  | { type: "partial"; plate: Partial<ParsedPlate> }
+  | { type: "invalid" }
 
-- `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
+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')
+}
+```
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kennzeichen",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "German license plate parsing and validation",
   "keywords": [
     "german",