docs: add reactivity guide and per-composable reactivity tables

Author: johnleider

apps/docs/src/components/app/AppErrorIcon.vue

@@ -0,0 +1,13 @@
+<script setup lang="ts">
+  defineProps<{
+    size?: string | number
+  }>()
+</script>
+
+<template>
+  <AppIcon
+    class="text-error"
+    icon="close"
+    :size="size ?? 16"
+  />
+</template>

apps/docs/src/components/app/AppSuccessIcon.vue

@@ -0,0 +1,13 @@
+<script setup lang="ts">
+  defineProps<{
+    size?: string | number
+  }>()
+</script>
+
+<template>
+  <AppIcon
+    class="text-success"
+    icon="success"
+    :size="size ?? 16"
+  />
+</template>

apps/docs/src/pages/composables/forms/create-form.md

@@ -57,6 +57,22 @@ import { useForm } from '@vuetify/v0'
 const form = useForm()
 ```
 
+## Reactivity
+
+`createForm` adds **reactive validation state** on top of `createRegistry`. Form-level and field-level state are fully reactive.
+
+| Property/Method | Reactive | Notes |
+| - | :-: | - |
+| `isValid` | <AppSuccessIcon /> | Computed from all fields |
+| `isValidating` | <AppSuccessIcon /> | Computed from all fields |
+| `ticket.value` | <AppSuccessIcon /> | ShallowRef, triggers validation on change |
+| `ticket.errors` | <AppSuccessIcon /> | ShallowRef array |
+| `ticket.isValid` | <AppSuccessIcon /> | ShallowRef (null/true/false) |
+| `ticket.isPristine` | <AppSuccessIcon /> | ShallowRef boolean |
+| `ticket.isValidating` | <AppSuccessIcon /> | ShallowRef boolean |
+| `get(id)` | <AppErrorIcon /> | Returns ticket with reactive refs |
+| `values()` | <AppErrorIcon /> | Use `useProxyRegistry()` for reactive collection |
+
 ## Architecture
 
 `createForm` extends `createRegistry` with validation capabilities:

apps/docs/src/pages/composables/foundation/create-context.md

@@ -99,4 +99,16 @@ Click the buttons to add notifications. Click a notification to dismiss it.
 
 :::
 
+## Reactivity
+
+`createContext` is a **factory function** that returns plain functions. It does not introduce reactivity itself—reactivity comes from the values you provide.
+
+| Return | Reactive | Notes |
+| - | :-: | - |
+| `useContext()` | <AppErrorIcon /> | Function, returns injected value |
+| Injected value | <AppSuccessIcon /> | If you provide refs/reactive objects |
+
+> [!TIP] Reactivity is what you provide
+> The context system is a transport layer. If you provide `ref()` or `reactive()` values, consumers get reactive access. Plain objects remain plain.
+
 <DocsApi />

apps/docs/src/pages/composables/foundation/create-plugin.md

@@ -100,4 +100,11 @@ flowchart LR
   install --> app.runWithContext
 ```
 
+## Reactivity
+
+`createPlugin` is a **factory function** that returns a Vue plugin object. It does not introduce reactivity—it's a vehicle for providing contexts at app level.
+
+> [!TIP] Reactivity lives in what you provide
+> The plugin is just the delivery mechanism. Reactive state comes from the contexts you provide via `provideContext()`.
+
 <DocsApi />

apps/docs/src/pages/composables/foundation/create-trinity.md

@@ -81,4 +81,15 @@ flowchart LR
   C --> Fallback
 ```
 
+## Reactivity
+
+`createTrinity` is a **factory function** that returns a tuple of functions and a default context. It does not introduce reactivity—it structures access to contexts you create.
+
+| Return | Reactive | Notes |
+| - | :-: | - |
+| `defaultContext` | <AppSuccessIcon /> | If the context object contains refs/reactive |
+
+> [!TIP] Trinity is a pattern, not a reactive primitive
+> The trinity pattern organizes your context into a consistent tuple. Reactivity depends on what you put in `defaultContext`.
+
 <DocsApi />

apps/docs/src/pages/composables/plugins/use-breakpoints.md

@@ -91,4 +91,19 @@ flowchart LR
   viewport --> breakpoint[name/flags]
 ```
 
+## Reactivity
+
+All breakpoint properties are reactive and automatically update when the viewport size changes.
+
+| Property | Reactive | Notes |
+| - | :-: | - |
+| `name` | <AppSuccessIcon /> | Current breakpoint name |
+| `width` | <AppSuccessIcon /> | Viewport width in pixels |
+| `height` | <AppSuccessIcon /> | Viewport height in pixels |
+| `isMobile` | <AppSuccessIcon /> | Below mobile breakpoint threshold |
+| `xs` / `sm` / `md` / `lg` / `xl` / `xxl` | <AppSuccessIcon /> | Exact breakpoint matches |
+| `smAndUp` / `mdAndUp` / `lgAndUp` / `xlAndUp` / `xxlAndUp` | <AppSuccessIcon /> | At or above breakpoint |
+| `smAndDown` / `mdAndDown` / `lgAndDown` / `xlAndDown` / `xxlAndDown` | <AppSuccessIcon /> | At or below breakpoint |
+| `breakpoints` | <AppErrorIcon /> | Static config object |
+
 <DocsApi />

apps/docs/src/pages/composables/plugins/use-date.md

@@ -410,3 +410,12 @@ This is intentional to prevent hydration mismatches. For SSR apps needing curren
    ```
 
 3. **Server timezone:** Set `TZ=UTC` environment variable on your server for consistent baseline
+
+## Reactivity
+
+The date context provides minimal reactivity, with the adapter being a static instance.
+
+| Property | Reactive | Notes |
+| - | :-: | - |
+| `locale` | <AppSuccessIcon /> | Computed from `useLocale` if available |
+| `adapter` | <AppErrorIcon /> | Static adapter instance |

apps/docs/src/pages/composables/plugins/use-features.md

@@ -238,4 +238,14 @@ flowchart TD
   createTokens --> useFeatures
 ```
 
+## Reactivity
+
+Feature flags inherit reactivity from `createGroup`. Selection state is reactive, but lookup methods return static values.
+
+| Property | Reactive | Notes |
+| - | :-: | - |
+| `selectedIds` | <AppSuccessIcon /> | Set of enabled feature IDs |
+| `selectedItems` | <AppSuccessIcon /> | Computed array of enabled features |
+| ticket `isSelected` | <AppSuccessIcon /> | Computed from `selectedIds` |
+
 <DocsApi />

apps/docs/src/pages/composables/plugins/use-hydration.md

@@ -73,4 +73,13 @@ flowchart LR
   hydrate --> isHydrated
 ```
 
+## Reactivity
+
+Hydration state is reactive and updates when the root component mounts.
+
+| Property | Reactive | Notes |
+| - | :-: | - |
+| `isHydrated` | <AppSuccessIcon /> | True after root component mounts |
+| `isSettled` | <AppSuccessIcon /> | True after next tick post-hydration |
+
 <DocsApi />