Use `useUrlControlledString` for search bars and toolbars where the value is controlled but should still mirror URL state.

This hook is useful when a component already owns a controlled `string` value, but you still want that value reflected in TanStack Router search params.

## Usage [#usage]

```tsx
import { useUrlControlledString } from "@tilt-legal/cubitt-components/utilities/hooks";

export function ToolbarSearch() {
  const [value, setValue] = useUrlControlledString({
    paramName: "files-search",
    defaultValue: "",
  });

  return (
    <input
      value={value}
      onChange={(event) => setValue(event.target.value)}
    />
  );
}
```

## Router registration [#router-registration]

When your app registers its TanStack Router, `paramName` narrows to known search keys from the route tree. TanStack Start/file-based apps usually get this automatically. Without registration, it remains a plain `string`.

## API [#api]

| Option                | Type                              | Description                                                                      | Default |
| --------------------- | --------------------------------- | -------------------------------------------------------------------------------- | ------- |
| `paramName`           | `string`                          | URL parameter name. Narrows to known search keys when your router is registered. | -       |
| `value`               | `string`                          | Controlled value (overrides internal and URL state)                              | -       |
| `defaultValue`        | `string`                          | Default value when uncontrolled                                                  | `""`    |
| `onChange`            | `(value: string) => void`         | Callback when the value changes                                                  | -       |
| `paramDefaultValue`   | `string`                          | URL default value (defaults to `defaultValue`)                                   | -       |
| `paramClearOnDefault` | `boolean`                         | Remove the parameter when value equals default                                   | `true`  |
| `paramThrottle`       | `number`                          | Throttle URL writes in milliseconds                                              | -       |
| `paramDebounce`       | `number`                          | Debounce URL writes in milliseconds                                              | -       |
| `onUrlValueChange`    | `(value: string \| null) => void` | Callback when the URL value changes                                              | -       |