@santi020k/lumen-react 0.4.0 → 1.2.0

package/README.md

@@ -37,8 +37,31 @@ export function SubscribeForm() {
 }
 ```
 
-For long articles, `Anchor` accepts an optional heading `depth` and `ScrollProgress` tracks the
-document without requiring a separate hook.
+## Forms
+
+`Form`, `Field`, `Label`, `FieldError`, and `ErrorSummary` provide the presentation and
+accessibility contract without replacing form state. Native-backed controls forward refs to their
+submitted DOM controls and work directly with React Hook Form's `register()`.
+
+For controlled composites, install the optional adapter:
+
+```bash
+pnpm add @santi020k/lumen-react-hook-form react-hook-form
+```
+
+It exports adapters for `Select`, `DatePicker`, `InputOTP`, and `ListBox`. React Hook Form owns
+validation, dirty/touched state, and submission state in this mode; do not also mount
+`useFormValidation` unless two validation sources are intentional.
+
+Zod and Yup schemas work through the official `@hookform/resolvers` package. Schema libraries stay
+optional application dependencies; Lumen consumes the resulting React Hook Form field errors
+without wrapping or changing the resolver contract.
+
+See the [forms guide](https://lumen.santi020k.com/docs/forms/react-hook-form) for typed examples.
+
+For long articles, `Anchor` accepts optional `depth`, `index`, and `description` metadata plus an
+`activationOffset`. It synchronizes the current link on click and scroll. `ScrollProgress` tracks
+the document without requiring a separate hook.
 
 ```tsx
 import { Anchor, ScrollProgress } from '@santi020k/lumen-react'
@@ -50,6 +73,13 @@ import { Anchor, ScrollProgress } from '@santi020k/lumen-react'
 ]} />
 ```
 
+Use `CopyButton` for clipboard actions on generated names, descriptions, messages, and links. Pass
+either a `value` or a `target` selector; `toast` opts into Lumen Toast feedback.
+
+```tsx
+<CopyButton value="https://lumen.santi020k.com" toast>Copy link</CopyButton>
+```
+
 ## Data visualization
 
 `Sparkline`, `BarChart`, `LineChart`, and `PieChart` use the shared `LumenChartSeries` contract and
@@ -95,23 +125,55 @@ Other React applications continue to consume the same package and exports normal
 ## Compatibility wrappers
 
 The common wrapper primitives preserve their underlying DOM handles with React 19's ref-as-prop
-contract. `Button`, `Link`, `ButtonLink`, and `Input` accept `ref` directly. Use `Button asChild`
-to apply the button contract to one existing React element without adding another DOM node:
+contract. `Button`, `ButtonLink`, `Link`, `Input`, `Textarea`, `Label`, `Badge`, `Card`, and
+`Skeleton` accept `ref` directly. Use `Button asChild` or `ButtonLink asChild` to apply the
+corresponding contract to one existing React element without adding another DOM node:
 
 ```tsx
-import { Button } from '@santi020k/lumen-react'
+import { Button, ButtonLink, NativeSelect } from '@santi020k/lumen-react'
 import NextLink from 'next/link'
 
 <Button asChild variant="secondary">
   <NextLink href="/projects">Projects</NextLink>
 </Button>
+
+<ButtonLink asChild variant="ghost">
+  <NextLink href="/docs">Docs</NextLink>
+</ButtonLink>
 ```
 
-`Input` keeps the native numeric `size` attribute. Use `visualSize="sm"` or `visualSize="lg"` for
-Lumen's visual size modifiers:
+`Input` and `NativeSelect` keep the native numeric `size` attribute. Use `visualSize="sm"` or
+`visualSize="lg"` for Lumen's visual size modifiers:
 
 ```tsx
 <Input size={32} visualSize="sm" />
+<NativeSelect size={8} visualSize="lg" />
+```
+
+## Context navigation
+
+Use `ContextNavigation` below a primary header when links change with a selected platform,
+product, or workspace. Pass the stable selector or identity through `context` and compose the
+related links with one independently named `NavigationMenu`. Long link sets scroll horizontally.
+
+```tsx
+import { ContextNavigation, NativeSelect, NavigationMenu } from '@santi020k/lumen-react'
+
+<ContextNavigation
+  context={(
+    <NativeSelect aria-label="Documentation platform" visualSize="sm">
+      <option>Web</option>
+      <option>Apple</option>
+      <option>Android</option>
+    </NativeSelect>
+  )}
+>
+  <NavigationMenu aria-label="Web documentation" variant="unstyled">
+    <a href="/docs/web" aria-current="page">Overview</a>
+    <a href="/docs/components">Components</a>
+    <a href="/docs/web/playground">Playground</a>
+  </NavigationMenu>
+</ContextNavigation>
 ```
 
 Use `Icon` for Lucide icons by name across framework adapters.
@@ -184,6 +246,14 @@ shortcuts, active toolbar state, and `{ html, text }` change details.
 `DataTable` can render structured `columns` and `rows` with the same selectable/sortable data
 attributes, and `VirtualList` exposes the shared range sizing attributes for app-level adapters.
 
+## Kanban boards
+
+Use `KanbanBoard`, `KanbanColumn`, and ordinary `Card` items for status-based workspaces. The
+`useKanban` hook supplies root, column, item, and dedicated handle props and emits controlled move
+requests for keyboard, mouse, and touch input. It never moves application data or DOM. Keep pending
+state, persistence, rollback, and workflow rules in the host. Use `Empty variant="compact"` inside
+columns and card-shaped `Skeleton` blocks while loading.
+
 ## Motion
 
 Use `ScrollReveal` for one entrance, `RevealGroup` for tokenized child staggering, and