orio-ui 1.27.0 → 1.28.0

package/dist/runtime/composables/useUrlSync.USAGE.md

@@ -0,0 +1,91 @@
+---
+kind: composable
+category: Composables
+purpose: sync state to URL query params, URL-backed state, persist state in URL, shareable URL state
+purpose-extras: filter URL persistence, query params sync
+short: bidirectional sync between a reactive object and URL query params; SSR-safe initial read, client-only writes
+invariants: true
+---
+
+# useUrlSync — agent-only invariants
+
+`useUrlSync(state, keys?)` keeps a reactive `Record<string, unknown>` in
+sync with the URL's query string. Nuxt-only (depends on `#imports`'s
+`useRoute`).
+
+## Invariants
+
+- **Initial population is synchronous and SSR-safe.** Reads `useRoute().query`
+  (populated by Nuxt from the request URL on the server) and writes
+  matching keys into `state.value` before child components mount —
+  no hydration mismatch.
+- **Reactive writes are client-only.** Uses
+  `useUrlSearchParams('history')` which only writes to
+  `window.location`. On the server the watcher never fires.
+- **`keys` is optional but recommended.**
+  - When omitted: initial population pulls *all* top-level keys
+    currently in the URL; ongoing sync watches *all* keys in
+    `state.value`. Easy to leak unrelated state into the URL.
+  - When provided: only listed keys go in either direction.
+- **Serialization conventions**:
+  - Plain values: `?key=value`.
+  - Nested objects: dot notation (`filters.category=shirts`).
+  - Arrays: bracket notation (`tags[0]=cats&tags[1]=dogs`).
+  - Combinations: mixed (`items[0].name=John`).
+  - `File` / `Blob` values: **silently skipped** (not serializable).
+  - Empty strings: **removed** from the URL.
+- **URL writes use `router.replace`-like semantics** (via
+  `useUrlSearchParams` `'history'` mode) — no new browser history
+  entry. Back button still goes to the previous page, not the
+  previous filter state.
+- **Watcher key**: the composable serializes only the synced keys to a
+  primitive string for cheap diffing — avoids deep-equality on File
+  arrays.
+- **Flatten/unflatten helpers** live in `utils/urlParams`. Forming the
+  same dot/bracket conventions from outside requires going through
+  those helpers, not building strings manually.
+
+## Gotchas
+
+- **Nuxt-only**: imports `useRoute` from `#imports`. Will not run in a
+  Vite/Vue-only consumer without Nuxt's auto-import config or a
+  manual shim.
+- **No two-way URL-changes-update-state listener.** This composable
+  flows state → URL, not URL → state, after the initial read. Back /
+  forward navigation does not re-populate the state.
+- **`keys` omitted = global sync.** Local UI state (open/close flags,
+  hover, cursor positions) accidentally listed in `state` will land in
+  the URL. Always pass an explicit `keys` array unless `state` IS the
+  URL state.
+- **Top-level key matching includes dotted and bracketed children**:
+  `key === "filter"` matches `filter`, `filter.tag`, `filter[0]`.
+- **`File` values are dropped**: the user-visible behavior is "I added
+  a file then the URL didn't update". By design, but surprising.
+
+## Quick reference
+
+```ts
+import { ref } from "vue";
+import { useUrlSync } from "../composables/useUrlSync";
+
+const filters = ref({
+  category: "",
+  tags: [] as string[],
+  sort: "newest",
+});
+
+// Sync only the listed keys — recommended.
+useUrlSync(filters, ["category", "tags", "sort"]);
+```
+
+```ts
+// State IS the URL state — sync all keys.
+const properties = ref<Record<string, string | File[]>>({});
+useUrlSync(properties);
+```
+
+## Related
+
+- `useFilter` — wraps this for filter groups; pass `urlSync: true`.
+- `utils/urlParams` — `flattenParams`, `unflattenParams`, `topLevelKeys`.
+- Public API reference: `docs/composables/use-url-sync.md`.

package/dist/runtime/composables/useValidation.USAGE.md

@@ -0,0 +1,100 @@
+---
+kind: composable
+category: Composables
+purpose: form validation, declarative form rules, field validation, error state
+short: declarative rule-based form validation with reactive errors keyed by field id and auto scroll-to-first-error
+invariants: true
+---
+
+# useValidation — agent-only invariants
+
+`useValidation(rules?)` returns `{ checkValidity, errors, clearError,
+clearAllErrors, changeRules }`. Errors are keyed by a field `id` that must
+match a real DOM element id so the composable can scroll the offending
+field into view.
+
+## Invariants
+
+- **`rules: ValidationRule[]`**: `{ model, id, validator, message? }`.
+  - `model: MaybeRef<any>` — the value to validate. Unwrapped via
+    `unref` at check time.
+  - `id: string` — the DOM id of the field. Must be unique and must
+    match an element in the DOM at validation time so `scrollIntoView`
+    works.
+  - `validator(model) => boolean` — returns true if valid.
+  - `message?: string` — error message; falls back to
+    `t("validation.fieldError")`.
+- **`errors`** is a reactive `Record<string, string | null>`. Truthy
+  string = error; `null` = no error.
+- **`checkValidity()`** clears all errors, runs every rule with
+  `reduceRight`, and returns true if all passed.
+- **`reduceRight` is used so that all rules execute** even after one
+  fails. The reducer is `(valid, rule) => validate(rule) && valid` —
+  `validate` runs unconditionally; the boolean is just aggregated.
+- **The first failing rule (in reduceRight order = bottom-up of the
+  array) is scrolled into view.** Later rules' errors are still set
+  but don't trigger another scroll because `errors[id]` is already
+  set (the guard inside `validate`).
+- **`changeRules(newRules)`** swaps the rule set at runtime — useful
+  when validation depends on a step / mode.
+- **i18n fallback**: `useI18n().t` is used when available; outside an
+  i18n context it falls back to the bundled `en.json`'s
+  `validation.fieldError` key.
+- **Exported helpers**: `isFilled(value)` (length-based truthy),
+  `isEmail(value)` (regex; empty string is treated as valid for
+  optional fields).
+
+## Gotchas
+
+- **`id` must match a real DOM element.** If it doesn't,
+  `scrollIntoView` is a no-op but the error still records. Test that
+  `id`s collide with rendered form controls — orio form components
+  generally need the same `id` passed via `ControlProps`.
+- **`reduceRight` order is reversed** relative to the rules array.
+  The "first" rule to fail (scroll target) is the LAST one in the
+  array. Order rules with the highest-priority field at the bottom
+  if scroll behavior matters.
+- **Errors don't auto-clear when the user fixes the field.** The
+  caller must call `clearError(id)` on input, or re-run `checkValidity`
+  on every change.
+- **No async validators.** `validator` must be synchronous; for
+  server-side checks, run them outside this composable.
+- **No structural rules** (required-if, cross-field). Compose them
+  inside individual validators.
+
+## Quick reference
+
+```ts
+import { useValidation, isFilled, isEmail } from "../composables/useValidation";
+
+const email = ref("");
+const name = ref("");
+
+const { checkValidity, errors, clearError } = useValidation([
+  { model: email, id: "email", validator: isEmail,
+    message: $t("validation.email") },
+  { model: name, id: "name", validator: isFilled },
+]);
+
+async function submit() {
+  if (!checkValidity()) return;
+  await api.save({ email: email.value, name: name.value });
+}
+```
+
+```vue
+<template>
+  <orio-input id="email" v-model="email" :error="errors.email"
+    @update:model-value="clearError('email')" />
+  <orio-input id="name" v-model="name" :error="errors.name"
+    @update:model-value="clearError('name')" />
+  <orio-button @click="submit">Submit</orio-button>
+</template>
+```
+
+## Related
+
+- `<orio-form>` — pairs with this for full-form validation.
+- `<orio-control-element>` — accepts the `error` string from
+  `errors[id]`.
+- Public API reference: `docs/composables/use-validation.md`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orio-ui",
-  "version": "1.27.0",
+  "version": "1.28.0",
   "description": "Modern Nuxt component library with theme support",
   "type": "module",
   "main": "./dist/module.mjs",
@@ -20,13 +20,19 @@
     "./styles": "./dist/runtime/assets/css/main.css",
     "./theme": "./dist/runtime/assets/css/colors.css"
   },
+  "bin": {
+    "orio-ui": "./bin/orio-ui.mjs"
+  },
   "files": [
+    "bin",
     "dist"
   ],
   "scripts": {
     "dev": "vitepress dev docs",
-    "prebuild": "node scripts/update-counts.mjs",
+    "prebuild": "node scripts/update-counts.mjs && node scripts/generate-routing.mjs",
     "build": "nuxt-module-build build",
+    "postbuild": "node scripts/emit-consumer-agents.mjs",
+    "prepare": "simple-git-hooks",
     "prepack": "npm run build",
     "test": "vitest",
     "test:unit": "vitest run",
@@ -68,6 +74,7 @@
     "prettier": "^3.7.4",
     "sass": "^1.70.0",
     "sass-embedded": "^1.92.1",
+    "simple-git-hooks": "^2.13.1",
     "typescript": "^5.9.3",
     "typescript-eslint": "^8.52.0",
     "vitepress": "^1.6.4",
@@ -76,6 +83,9 @@
     "vue": "^3.5.13",
     "vue-tsc": "^3.2.1"
   },
+  "simple-git-hooks": {
+    "pre-commit": "node scripts/generate-routing.mjs && git add CLAUDE.md .claude/agents/component-worker.md .claude/agents/component-finder.md"
+  },
   "peerDependencies": {
     "nuxt": "^3.0.0 || ^4.0.0",
     "vue": "^3.3.0"