feat: finalize 0.2.0 — locale date vocab, completions polish, pre-release fixes

Wraps up the 0.2.0 work (locale packs + ranked completions, plan 031) and the
pre-release review pass.

- Locale packs own natural-language date vocabulary: deictics/day parts,
  relative frames, month-date fillers, calendar periods, compact CJK offsets.
- Pin bare midday phrases (midi/mediodía/meio-dia/中午/正午) to today like
  English `noon`; midnight keeps English's forward-roll. Adds regression tests
  and records the policy in plan 031 (pre-release review must-fix).
- Drop the redundant future-prefix `parts` fallback in offset parsing — fully
  superseded by the prefix-shifted parse; removes a latent mis-parse surface.
- Ranked completions surface plus site locale/completions demos.
- Docs: CONTEXT entry list, architecture module table, README (root + package),
  plans 005/031, wiki decisions/inspiration, backlog follow-ups.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: Aymericr

.gitignore

@@ -29,3 +29,4 @@ packages/lingo/bench/ai-eval.json
 *.log
 .DS_Store
 .vercel
+/video

CONTEXT.md

@@ -112,8 +112,8 @@ its value. Fields never rewrite text while typing (D6).
 ## Infrastructure nouns
 
 **Entry:** a published subpath — `.`, `./core`, `./date`, `./dom`, `./element`,
-`./describe`, `./catalog`, `./schema`, `./ai`, `./mcp`, `./react`, `./complete`.
-*Avoid: subpackage, plugin.*
+`./describe`, `./catalog`, `./schema`, `./ai`, `./mcp`, `./react`, `./complete`,
+`./locales/*`. *Avoid: subpackage, plugin.*
 
 **Catalog:** the read-only query surface (`./catalog`) over built-in
 unit/kind/currency data — list kinds/units, resolve refs, related units,

README.md

@@ -14,8 +14,9 @@ strings: `"5'11\""`, `"1½ cups"`, `"twenty-five kg"`, `"3pm EST"`,
 `"1,234 kg"`. Your database wants canonical values: one number in one unit,
 one ISO date. The library is the layer in between: natural-language
 quantities, units, dates, and ranges parsed into validated values, then
-humanized back. Zero dependencies; English-first parsing with locale-aware
-formatting (locale packs are on the roadmap, plan 013).
+humanized back. Zero dependencies; English by default with opt-in locale packs
+(Spanish, French, Portuguese, Chinese, Japanese, en-GB) for parsing, plus
+locale-aware number formatting via `Intl`.
 
 **For the web.** Use one text field instead of a value box plus a unit dropdown:
 

apps/site/package.json

@@ -17,6 +17,7 @@
   "dependencies": {
     "@base-ui/react": "^1.6.0",
     "@pascal-app/lingo": "workspace:*",
+    "@vercel/analytics": "^2.0.1",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "geist": "^1.7.2",

apps/site/src/app/docs/page.tsx

@@ -1,4 +1,5 @@
 import { allKinds } from '@pascal-app/lingo'
+import { ISSUE_CODES } from '@pascal-app/lingo/schema'
 import type { Metadata } from 'next'
 
 import { EscalationLab } from '@/app/escalation/escalation-lab'
@@ -182,39 +183,8 @@ const formSchemaSnippet = `import { standardSchemaResolver } from '@hookform/res
 // user types "5 kg" / picks a date; canonical on submit
 useForm({ resolver: standardSchemaResolver(shipment) })`
 
-const issueCodes = [
-  'EMPTY',
-  'NO_VALUE',
-  'UNKNOWN_UNIT',
-  'KIND_MISMATCH',
-  'RANGE_KIND_MISMATCH',
-  'CONVERSION_KIND_MISMATCH',
-  'TRAILING_INPUT',
-  'SINGLE_VALUE_EXPECTED',
-  'APPROX_NOT_ALLOWED',
-  'UNIT_REQUIRED',
-  'CONVERSION_NOT_ALLOWED',
-  'NUMBER_FORMAT',
-  'NONFINITE',
-  'RANGE_MIN',
-  'RANGE_MAX',
-  'RANGE_OPEN_BOUND_NOT_ALLOWED',
-  'REQUIRED',
-  'UNSUPPORTED_DATE',
-  'NOW_REQUIRED',
-  'TYPO_CORRECTED',
-  'AMBIGUOUS_NUMBER',
-  'AMBIGUOUS_UNIT',
-  'AMBIGUOUS_DATE',
-  'RANGE_REVERSED',
-  'COMPOUND_OVERFLOW',
-  'CIVIL_AVERAGE',
-  'UNIT_ASSUMED',
-  'WEEKDAY_ASSUMED_NEXT',
-  'SLANG_UNIT',
-  'TZ_IGNORED',
-  'AMBIGUOUS_TIMEZONE',
-]
+// Sourced from the package so the badge wall can't drift from IssueCode.
+const issueCodes = Object.keys(ISSUE_CODES)
 
 const DOCS_DESCRIPTION =
   'Make forms easier, LLM tools safer. One parser for forgiving human forms and stricter tool schemas: parse, strictness, forms, AI tool fields, MCP, convert, currency, dates, and API reference.'

apps/site/src/app/globals.css

@@ -897,8 +897,12 @@ p {
   --hero-cursor-duration: 92ms;
 }
 
+/* Duration must match FIX_CURSOR_TRAVEL_MS in universal-input.tsx. */
 .hero-demo-cursor[data-state="fix"] {
-  --hero-cursor-duration: 620ms;
+  --hero-cursor-duration: 950ms;
+  transition:
+    opacity var(--motion-fast) var(--ease-out),
+    transform var(--hero-cursor-duration) cubic-bezier(0.3, 0.75, 0.3, 1);
 }
 
 .hero-demo-cursor[data-state="clicking"] {

apps/site/src/app/layout.tsx

@@ -1,3 +1,4 @@
+import { Analytics } from '@vercel/analytics/next'
 import { GeistMono } from 'geist/font/mono'
 import { GeistSans } from 'geist/font/sans'
 import type { Metadata } from 'next'
@@ -125,6 +126,7 @@ export default function RootLayout({
             </footer>
           </MotionProvider>
         </ThemeProvider>
+        <Analytics />
       </body>
     </html>
   )

apps/site/src/components/site/completions-demo.tsx

@@ -1,6 +1,7 @@
 'use client'
 
 import { type Completion, type CompletionSource, completions } from '@pascal-app/lingo/complete'
+import { parseDate, parseDateRange } from '@pascal-app/lingo/date'
 import { AnimatePresence, m, useReducedMotion } from 'motion/react'
 import { useEffect, useId, useMemo, useRef, useState } from 'react'
 
@@ -12,7 +13,14 @@ import { Input } from '@/components/ui/input'
 import { Label } from '@/components/ui/label'
 import { cn } from '@/lib/utils'
 
-const EXAMPLES = ['2 f', '8 oz', '10 kg to 16', '30 min to 2', '2 h', '5'] as const
+const EXAMPLES = [
+  'noon tomorrow',
+  '3days starting tomorrow',
+  '$10',
+  '2 f',
+  '10 kg to 16',
+  '5',
+] as const
 const DEBOUNCE_MS = 140
 const PANEL_EASE: [number, number, number, number] = [0.16, 1, 0.3, 1]
 
@@ -25,6 +33,8 @@ const SOURCE_ORDER: CompletionSource[] = [
   'unit-prefix',
   'implied-unit',
   'range-implied',
+  'cross-kind',
+  'date',
 ]
 
 const SOURCE_META: Record<CompletionSource, { label: string; hint: string; badgeClass: string }> = {
@@ -58,12 +68,26 @@ const SOURCE_META: Record<CompletionSource, { label: string; hint: string; badge
     hint: 'Open ranges fan out to kg, lb, m, ft, …',
     badgeClass: 'border-orange-500/25 bg-orange-500/10 text-orange-950 dark:text-orange-100',
   },
+  'cross-kind': {
+    label: 'Different kind',
+    hint: 'Optimistic reading when field kind rejects the parse',
+    badgeClass: 'border-fuchsia-500/25 bg-fuchsia-500/10 text-fuchsia-900 dark:text-fuchsia-100',
+  },
+  date: {
+    label: 'Date & time',
+    hint: 'Injected date parser from @pascal-app/lingo/date',
+    badgeClass: 'border-cyan-500/25 bg-cyan-500/10 text-cyan-900 dark:text-cyan-100',
+  },
 }
 
 const DEFAULT_SOURCES = Object.fromEntries(SOURCE_ORDER.map((source) => [source, true])) as Record<
   CompletionSource,
   boolean
 >
+const PILL_ACTIVE_CLASS = 'bg-muted text-foreground hover:bg-muted/80'
+const FILTER_PILL_INACTIVE_CLASS =
+  'bg-background text-muted-foreground line-through hover:bg-muted/30 hover:text-muted-foreground'
+const SELECT_PILL_INACTIVE_CLASS = 'bg-background text-muted-foreground hover:bg-muted/30'
 
 function useDebouncedValue<T>(value: T, delayMs: number) {
   const [debounced, setDebounced] = useState(value)
@@ -100,7 +124,7 @@ export function CompletionsDemo() {
   const [value, setValue] = useState('2 f')
   const [activeIndex, setActiveIndex] = useState(0)
   const [sources, setSources] = useState(DEFAULT_SOURCES)
-  const [fieldKind, setFieldKind] = useState<FieldKind>('mass')
+  const [fieldKind, setFieldKind] = useState<FieldKind>('off')
   const [customUnits, setCustomUnits] = useState('')
   const listRef = useRef<HTMLDivElement>(null)
 
@@ -117,6 +141,11 @@ export function CompletionsDemo() {
   const rawItems = useMemo(
     () =>
       completions(query, {
+        date: (text) => {
+          const now = new Date()
+          const single = parseDate(text, { now })
+          return single.ok ? single : parseDateRange(text, { now })
+        },
         limit: 12,
         kind: fieldKind === 'off' ? undefined : fieldKind,
         units: parsedUnits,
@@ -185,7 +214,10 @@ export function CompletionsDemo() {
               ).map(([kind, label]) => (
                 <Button
                   aria-pressed={fieldKind === kind}
-                  className="h-7 rounded-full px-2.5 text-xs shadow-none"
+                  className={cn(
+                    'h-7 rounded-full px-2.5 text-xs shadow-none',
+                    fieldKind === kind ? PILL_ACTIVE_CLASS : SELECT_PILL_INACTIVE_CLASS,
+                  )}
                   key={kind}
                   onClick={() => setFieldKind(kind)}
                   size="sm"
@@ -230,7 +262,7 @@ export function CompletionsDemo() {
                     aria-pressed={on}
                     className={cn(
                       'h-7 rounded-full px-2.5 text-xs shadow-none',
-                      on && meta.badgeClass,
+                      on ? PILL_ACTIVE_CLASS : FILTER_PILL_INACTIVE_CLASS,
                     )}
                     key={source}
                     onClick={() => toggleSource(source)}

apps/site/src/components/site/docs-search.tsx

@@ -26,18 +26,44 @@ function isTypingTarget(target: EventTarget | null) {
   )
 }
 
-function scoreResult(searchableText: string, query: string) {
-  if (!query) {
-    return 0
+interface SearchableItem {
+  searchableKeywords: string[]
+  searchableText: string
+  searchableTitle: string
+}
+
+function scoreWord(item: SearchableItem, word: string) {
+  if (item.searchableTitle.startsWith(word)) {
+    return 6
+  }
+  if (item.searchableTitle.includes(word)) {
+    return 4
+  }
+  if (item.searchableKeywords.some((keyword) => keyword.startsWith(word))) {
+    return 3
+  }
+  if (item.searchableText.includes(word)) {
+    return 1
   }
+  return 0
+}
 
+// Every query word must match somewhere; title > keyword > body.
+function scoreResult(item: SearchableItem, query: string) {
   const words = query.toLowerCase().split(/\s+/).filter(Boolean)
-  return words.reduce((score, word) => {
-    if (searchableText.includes(word)) {
-      return score + (searchableText.startsWith(word) ? 3 : 1)
+  if (words.length === 0) {
+    return 0
+  }
+
+  let total = 0
+  for (const word of words) {
+    const score = scoreWord(item, word)
+    if (score === 0) {
+      return 0
     }
-    return score
-  }, 0)
+    total += score
+  }
+  return total
 }
 
 export function DocsSearch({ className }: { className?: string }) {
@@ -59,7 +85,7 @@ export function DocsSearch({ className }: { className?: string }) {
     }
 
     return docsSearchIndex
-      .map((item) => ({ ...item, score: scoreResult(item.searchableText, trimmed) }))
+      .map((item) => ({ ...item, score: scoreResult(item, trimmed) }))
       .filter((item) => item.score > 0)
       .sort((a, b) => b.score - a.score || a.title.localeCompare(b.title))
       .slice(0, 10)

apps/site/src/components/site/locale-select.tsx

@@ -0,0 +1,91 @@
+'use client'
+
+import { ChevronDownIcon } from 'lucide-react'
+
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuRadioGroup,
+  DropdownMenuRadioItem,
+  DropdownMenuTrigger,
+} from '@/components/ui/dropdown-menu'
+import { LOCALE_META, type LocaleChoice, localeMeta } from '@/lib/locale-meta'
+import { cn } from '@/lib/utils'
+
+function LocaleFlag({ flag, className }: { flag: string; className?: string }) {
+  return (
+    <span
+      aria-hidden="true"
+      className={cn(
+        'inline-flex size-5 shrink-0 items-center justify-center text-[1.125rem] leading-none',
+        className,
+      )}
+    >
+      {flag}
+    </span>
+  )
+}
+
+function LocaleOptionLabel({ flag, label }: { flag: string; label: string }) {
+  return (
+    <span className="flex min-w-0 items-center gap-2.5">
+      <LocaleFlag flag={flag} />
+      <span className="truncate">{label}</span>
+    </span>
+  )
+}
+
+export function LocaleSelect({
+  className,
+  id,
+  onValueChange,
+  value,
+}: {
+  className?: string
+  id?: string
+  onValueChange: (value: LocaleChoice) => void
+  value: LocaleChoice
+}) {
+  const current = localeMeta(value) ?? LOCALE_META[0]!
+
+  return (
+    <DropdownMenu>
+      <DropdownMenuTrigger
+        aria-label="Locale"
+        className={cn(
+          'inline-flex h-8 w-full min-w-36 cursor-pointer items-center justify-between gap-2 rounded-lg border border-transparent bg-[var(--control-background)] py-1 pr-2 pl-2.5 text-sm shadow-[var(--surface-ring)] outline-none transition-[background-color,color,border-color,box-shadow] duration-[var(--motion-fast)] ease-[var(--ease-out)] hover:bg-[var(--control-hover-background)] focus-visible:border-[var(--control-focus-border)] focus-visible:ring-3 focus-visible:ring-ring/50 data-popup-open:bg-[var(--control-hover-background)]',
+          className,
+        )}
+        id={id}
+      >
+        <LocaleOptionLabel flag={current.flag} label={current.label} />
+        <ChevronDownIcon aria-hidden="true" className="size-4 shrink-0 text-muted-foreground" />
+      </DropdownMenuTrigger>
+      <DropdownMenuContent align="end" className="w-52" sideOffset={6}>
+        <DropdownMenuRadioGroup
+          onValueChange={(next) => onValueChange(next as LocaleChoice)}
+          value={value}
+        >
+          {LOCALE_META.map((entry) => (
+            <DropdownMenuRadioItem key={entry.value} value={entry.value}>
+              <LocaleOptionLabel flag={entry.flag} label={entry.label} />
+            </DropdownMenuRadioItem>
+          ))}
+        </DropdownMenuRadioGroup>
+      </DropdownMenuContent>
+    </DropdownMenu>
+  )
+}
+
+export function LocaleBadge({ locale }: { locale: string | undefined }) {
+  const meta = localeMeta(locale)
+  if (!meta) {
+    return <span className="numeric-mono text-foreground">{locale ?? '—'}</span>
+  }
+  return (
+    <span className="inline-flex items-center gap-1.5">
+      <LocaleFlag className="size-4 text-base" flag={meta.flag} />
+      <span className="numeric-mono text-foreground">{meta.value}</span>
+    </span>
+  )
+}