flet-box 1.0.4 → 1.0.6

package/docs/widget/DraggBox.md

@@ -0,0 +1,129 @@
+# DraggBox
+
+DraggBox wraps a child so it can be dragged with the native drag-and-drop API. It tags the payload with data and an optional group so matching DroppBox targets can accept it.
+
+## When to use it
+
+Use it to build kanban boards, sortable lists or any drag-to-rearrange interface.
+
+## Quick start
+
+```javascript
+import { DraggBox, Text } from "flet-box";
+
+const item = DraggBox({
+  child: Text({ text: "Drag me" }),
+});
+```
+
+> The prop table is generated from `src/index.d.ts`; the examples use only documented props.
+
+## Props
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `child` | `Widget` | A single child widget. Alias: `children` for a list. |
+| `data` | `any` | Array of values or `{ label, value }` slices. |
+| `group` | `string` | Drag group name; only matching targets accept the item. |
+| `disabled` | `boolean` | Disables interaction and shows the non-interactive state. |
+| `onDragStart` | `(event: DragEvent, data: any) => void` | Fired when dragging starts. |
+| `onDragEnd` | `(event: DragEvent, data: any) => void` | Fired when dragging ends. |
+| `dragImage` | `HTMLElement` | Custom image shown while dragging. |
+| `cloneOnDrag` | `boolean` | Keeps the original element while dragging a clone. |
+| `opacity` | `number` | Opacity from 0 (invisible) to 1 (fully opaque). |
+| `dragOverlayColor` | `Color` | Color used for the drag overlay. |
+| `dragBorderColor` | `Color` | Border color for the drag. |
+
+### Common props
+
+Every widget also accepts these shared props — see [common props](COMMON_PROPS.md) for the full rules and aliases.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `width` | `Size` | Width of the widget. A number is pixels; a string uses any CSS unit. |
+| `height` | `Size` | Height of the widget. A number is pixels; a string uses any CSS unit. |
+| `size` | `Size` | Overall size preset or pixel value, depending on the widget. |
+| `padding` | `Padding` | Space inside the widget, between its content and its border. |
+| `margin` | `Margin` | Space outside the widget, between it and its neighbors. |
+| `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
+| `color` | `Color` | Foreground color, usually the text or icon color. |
+| `borderRadius` | `number \| string` | Rounds the corners of the widget. |
+| `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |
+| `shadow` | `string` | Raw CSS `box-shadow` value, for a custom shadow. |
+| `opacity` | `number` | Opacity from 0 (invisible) to 1 (fully opaque). |
+| `visible` | `boolean` | Whether the widget is rendered and visible. |
+| `disabled` | `boolean` | Disables interaction and shows the non-interactive state. |
+| `onPress` | `(widget: Widget) => void` | Callback fired when the widget is pressed. Alias: `onClick`. |
+| `onClick` | `(widget: Widget) => void` | Callback fired when the widget is clicked. Alias: `onPress`. |
+| `id` | `string` | DOM `id` for the rendered element. |
+| `className` | `string` | CSS class names applied to the rendered element. |
+| `ref` | `(widget: Widget) => void` | Callback that receives the underlying DOM node. |
+| `disableTransform` | `boolean` | Disables the default press/scale transform animation. |
+
+## Examples
+
+### Everyday
+
+```javascript
+import { Card, DraggBox, Text } from "flet-box";
+
+const task = DraggBox({
+  child: Card({ padding: 12, child: Text({ text: "Write docs" }) }),
+  group: "tasks",
+  data: { id: 1 },
+  onDragEnd: (event, data) => console.log(data),
+});
+```
+
+### Full
+
+```javascript
+import { Card, DraggBox, Text } from "flet-box";
+
+const task = DraggBox({
+  child: Card({
+    padding: 16,
+    child: Text({ text: "Ship the release" }),
+  }),
+  group: "kanban",
+  data: { id: "task-42", title: "Ship the release" },
+  cloneOnDrag: true,
+  opacity: 0.6,
+  dragOverlayColor: "#eff6ff",
+  dragBorderColor: "#2563eb",
+  onDragStart: (event, data) => console.log("start", data),
+  onDragEnd: (event, data) => console.log("end", data),
+});
+```
+
+## Tips
+
+- Give draggable items a group and have targets list it in acceptGroups to control what can be dropped.
+- Use cloneOnDrag when the original should remain in place while a copy is dragged.
+- Set data to the payload the drop target needs, not just the visual content.
+
+## Accessibility
+
+- Provide a non-drag alternative such as buttons or a menu so keyboard users can move items.
+- Ensure onDragStart and onDragEnd give feedback so changes are perceivable.
+
+## Behavior
+
+- Drag events surface the original payload via the data argument in onDragStart and onDragEnd.
+- Setting disabled turns the child back into a non-draggable element.
+
+## Related widgets
+
+- [DroppBox](DroppBox.md)
+- [Card](Card.md)
+- [ListView](ListView.md)
+
+---
+
+## Continue reading
+
+- **Previous:** [Video](Video.md)
+- **Next:** [DroppBox](DroppBox.md)
+- **Index:** [Widget index](README.md) · [Start here](START_HERE.md)
+
+You are reading **Chapter 7 · Media and drag & drop** (3 of 4).

package/docs/widget/Drawer.md

@@ -0,0 +1,135 @@
+# Drawer
+
+## Overview
+`Drawer` slides a panel in from the left or right edge, over a dimmed, blurred backdrop. Calling it is the action: `Drawer({ ... })` builds a fixed overlay (covering the viewport), **appends it to `document.body`**, and returns a controller object `{ open, close, toggle, destroy, element }` — not an element you place in your tree. The first open animates the panel out; `Escape` and clicking the backdrop close it when enabled. A module-level singleton also exposes `openDrawer()`, `closeDrawer()`, `toggleDrawer()`, and `destroyDrawer()` that act on the most recently created drawer.
+
+## When to use
+- Slide out primary navigation (a hamburger menu) from the side of the screen.
+- Offer a panel with filters, profile actions, or a mini-menu without leaving the page.
+
+## Import
+
+```javascript
+import { Drawer, Text } from "flet-box";
+```
+
+## Basic example
+
+The smallest useful version. Start here if this widget is new to you.
+
+```javascript
+import { Drawer, Text } from "flet-box";
+
+const drawer = Drawer({
+  body: [Text({ text: "Menu" })],
+});
+
+drawer.open();
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `header` | Widget | — | Fixed top section of the panel. |
+| `body` | Widget[] | `[]` | Scrollable middle section. |
+| `footer` | Widget | — | Fixed bottom section of the panel. |
+| `position` | `'left'`/`'right'` | `'left'` | Which edge the panel slides from. |
+| `width` | number | `280` | Panel width in pixels (or a CSS size). |
+| `onClose` | function | — | Fired when the panel finishes closing. |
+| `onOpen` | function | — | Fired when the panel finishes opening. |
+| `blur` | boolean | `true` | Blur the backdrop with `backdropFilter`. |
+| `blurIntensity` | number | `4` | Backdrop blur radius in px. |
+| `bgColor` | Color | `colors.surface` | Panel background. |
+| `elevation` | number | `4` | Side shadow strength. |
+| `closeOnOverlayClick` | boolean | `true` | Close when the backdrop is clicked. |
+| `closeOnEsc` | boolean | `true` | Close when `Escape` is pressed. |
+| `borderRadius` | number | `24` | Corner radius on the panel's inner edge. |
+| `margin` | number | `0` | Inset the panel from the top/bottom edges. |
+
+These are the props specific to `Drawer`. The panel is built from `Container`/`Column`/`Text` under the hood.
+
+## Instance methods
+
+The object returned by `Drawer`:
+
+- `open()` — show the panel (slide-in + fade the backdrop).
+- `close()` — hide it (slide-out, then `display: none` after 300 ms).
+- `toggle()` — invert the current state.
+- `destroy()` — remove the element from `document.body` and release listeners.
+- `element` — the overlay `HTMLElement`, if you need direct access.
+
+Also `document.body` receives the overlay immediately: no placement step needed.
+
+## Global helpers
+
+The last drawer created is remembered, so you can drive it from anywhere:
+
+- `openDrawer()` · `closeDrawer()` · `toggleDrawer()` · `destroyDrawer()`
+
+If no drawer exists yet these log a warning and do nothing.
+
+## Examples
+
+### Everyday example
+
+```javascript
+import { Drawer, Text, DrawerItem } from "flet-box";
+
+const drawer = Drawer({
+  header: Text({ text: "Menu", size: 18, weight: "bold", padding: 16 }),
+  body: [
+    DrawerItem({ icon: "home", label: "Home" }),
+    DrawerItem({ icon: "person", label: "Profile" }),
+  ],
+});
+
+document.querySelector("#open").addEventListener("click", () => drawer.open());
+```
+
+### Full example
+
+```javascript
+import { Drawer, openDrawer, Text, Button } from "flet-box";
+
+Drawer({
+  position: "right",
+  width: 320,
+  header: Text({ text: "Filters", size: 18, weight: "bold", padding: 16 }),
+  body: [
+    Button({ text: "Reset", onPress: () => console.log("reset filters") }),
+  ],
+  footer: Text({ text: "Applied", padding: 16 }),
+  closeOnEsc: true,
+  borderRadius: 20,
+});
+
+// somewhere else in your app:
+openDrawer();
+```
+
+## Notes
+
+- `Drawer` builds a fixed overlay `100vw × 100vh` at `z-index: 10000` and appends it to `document.body` during the call. Re-mount it once (e.g. in a `Scaffold`'s `drawer` prop) and drive it with the controller or the global helpers.
+- `onOpen` fires immediately on open (before the animation ends) and `onClose` fires after the 300 ms close animation, right when the element is hidden.
+- While open, the panel is `transform: translateX(0)`; corner rounding applies to the edge facing the screen center (`top/bottomRight` for left panels and the mirror for right ones).
+- The drawer keeps itself sized to the viewport on resize (`dimensions.addListener`), and `destroy()` removes that listener and the `keydown` handler.
+- When you pass `drawer` to a [Scaffold](Scaffold.md), a `menu` icon in the [AppBar](AppBar.md) opens it, `closeDrawerOnNavigate` can close it on route change, and the shell tears it down with its `_cleanup`.
+- Keydown (`Escape`) and resize listeners are only active while the drawer exists or is open — no leaks on the normal lifecycle.
+
+## Related widgets
+- [DrawerItem](DrawerItem.md)
+- [Scaffold](Scaffold.md)
+- [AppBar](AppBar.md)
+- [BottomSheet](BottomSheet.md)
+- [Modal](Modal.md)
+
+---
+
+## Continue reading
+
+- **Previous:** [AppBar](AppBar.md)
+- **Next:** [DrawerItem](DrawerItem.md)
+- **Index:** [Widget index](README.md) · [Start here](START_HERE.md)
+
+You are reading **Chapter 8 · App navigation** (4 of 8).

package/docs/widget/DrawerItem.md

@@ -0,0 +1,98 @@
+# DrawerItem
+
+## Overview
+`DrawerItem` is a single tappable row for a [Drawer](Drawer.md): an optional `icon`, a `label`, and a trailing chevron. It is **router-aware** — when a `route` is set it calls `goTo(route)` on tap, highlights itself when its route matches the current path, dims to unselected when another item is chosen, and closes the drawer after navigation (`closeOnPress` defaults to `true`). Keyboard-friendly: `role="button"`, focusable, and activated with `Enter` or `Space`.
+
+## When to use
+- Build the body of a navigation drawer with auto-selection and routing built in.
+- Reuse the same items in a fixed side bar: selection follows the URL.
+
+## Import
+
+```javascript
+import { DrawerItem } from "flet-box";
+```
+
+## Basic example
+
+The smallest useful version. Start here if this widget is new to you.
+
+```javascript
+import { DrawerItem } from "flet-box";
+
+DrawerItem({ icon: "home", label: "Home" });
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `icon` | string | — | Material icon name shown before the label. |
+| `label` | string | — | The row text (used as the selected marker id too). |
+| `route` | string | — | Route to navigate to on tap via `goTo`. |
+| `onPress` | function | — | Extra handler fired on tap. |
+| `onSelect` | function | — | Fired when this item becomes selected. |
+| `trailingIcon` | string | `"chevron_right"` | Icon at the right edge. |
+| `trailingIconColor` | Color | follows selection | Color of the trailing icon. |
+| `iconColor` | Color | follows selection | Color of the leading icon. |
+| `selectedColor` | Color | `colors.primary` | Text/icon color while selected (background tint is this color at 15% alpha). |
+| `unselectedColor` | Color | `colors.text` | Text/icon color while unselected. |
+| `hintColor` | Color | `colors.gray100` | Hover background while unselected. |
+| `closeOnPress` | boolean | `true` | Close the drawer (`closeDrawer()`) after navigating. |
+| `disableTransform` | boolean | `true` | Keep the row from scaling/transforming on hover. |
+
+These are the props specific to `DrawerItem`. It also accepts every [common prop](COMMON_PROPS.md) (including `gap` and `borderRadius`), applied to the row `Container`.
+
+## Examples
+
+### Everyday example
+
+```javascript
+import { Drawer, DrawerItem } from "flet-box";
+
+Drawer({
+  body: [
+    DrawerItem({ icon: "home", label: "Home", route: "/" }),
+    DrawerItem({ icon: "settings", label: "Settings", route: "/settings" }),
+    DrawerItem({ icon: "logout", label: "Sign out", route: "/logout" }),
+  ],
+});
+```
+
+### Full example
+
+```javascript
+import { DrawerItem } from "flet-box";
+
+DrawerItem({
+  icon: "notifications",
+  label: "Notifications (3)",
+  route: "/notifications",
+  trailingIcon: "chevron_right",
+  selectedColor: "#2563eb",
+  onSelect: () => console.log("opened notifications"),
+});
+```
+
+## Notes
+
+- Reads the router state (`getCurrentPath()` + `subscribe`) to track selection. Initialize the router first (see the [Routing guide](../guides/router.md)); the item matches when `route === currentPath`, and `route: "/"` also matches the empty path.
+- Only one item stays selected: choosing an item tells the others to deselect (an internal event is shared across all instances).
+- With no `route`, tapping still fires `onPress`/`onSelect` and the row follows manual selection, but it won't navigate.
+- It works identically inside a [Drawer](Drawer.md) or pinned to a side of a [Scaffold](Scaffold.md)/[CollapsibleSideBar](CollapsibleSideBar.md) — the highlight always follows the URL.
+- Cleanup unsubscribes both the router subscription and the selection event, so rows are safe to remove.
+
+## Related widgets
+- [Drawer](Drawer.md)
+- [Scaffold](Scaffold.md)
+- [Icon](Icon.md)
+
+---
+
+## Continue reading
+
+- **Previous:** [Drawer](Drawer.md)
+- **Next:** [BottomNavigation](BottomNavigation.md)
+- **Index:** [Widget index](README.md) · [Start here](START_HERE.md)
+
+You are reading **Chapter 8 · App navigation** (5 of 8).

package/docs/widget/Dropdown.md

@@ -0,0 +1,139 @@
+# Dropdown
+
+A select control that shows the current choice and opens a menu of options when clicked.
+
+## When to use it
+
+Use Dropdown when the option list is long enough that radios would crowd the page.
+
+## Quick start
+
+```javascript
+import { Dropdown } from "flet-box";
+
+const city = Dropdown({
+  options: ["Berlin", "Paris", "Tokyo"],
+  placeholder: "Choose a city",
+});
+```
+
+> The prop table is generated from `src/index.d.ts`; the examples use only documented props.
+
+## Props
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `options` | `(string \| DropdownOption)[]` | Available options for a selection widget. |
+| `value` | `any` | Current value controlled by the widget. |
+| `placeholder` | `string` | Fallback text shown while the ad is unavailable. |
+| `disabled` | `boolean` | Disables interaction and shows the non-interactive state. |
+| `label` | `string` | Label or caption shown near the control. |
+| `error` | `boolean` | Error flag or message shown under the field. |
+| `variant` | `'outlined' \| 'filled'` | Visual variation or style preset. |
+| `size` | `'small' \| 'medium' \| 'large'` | Overall size preset or pixel value, depending on the widget. |
+| `borderRadius` | `number` | Rounds the corners of the widget. |
+| `color` | `Color` | Foreground color, usually the text or icon color. |
+| `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
+| `textColor` | `Color` | Color of the button label. |
+| `optionHoverColor` | `Color` | Background color of an option while hovered. |
+| `clearable` | `boolean` | Shows a button that clears the field. |
+| `width` | `number \| string` | Width of the widget. A number is pixels; a string uses any CSS unit. |
+| `portal` | `boolean` | Renders the dropdown menu in a portal above the page. |
+| `onChange` | `(value: any, label: string) => void` | Fired when the value changes. |
+
+### Common props
+
+Every widget also accepts these shared props — see [common props](COMMON_PROPS.md) for the full rules and aliases.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `width` | `Size` | Width of the widget. A number is pixels; a string uses any CSS unit. |
+| `height` | `Size` | Height of the widget. A number is pixels; a string uses any CSS unit. |
+| `size` | `Size` | Overall size preset or pixel value, depending on the widget. |
+| `padding` | `Padding` | Space inside the widget, between its content and its border. |
+| `margin` | `Margin` | Space outside the widget, between it and its neighbors. |
+| `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
+| `color` | `Color` | Foreground color, usually the text or icon color. |
+| `borderRadius` | `number \| string` | Rounds the corners of the widget. |
+| `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |
+| `shadow` | `string` | Raw CSS `box-shadow` value, for a custom shadow. |
+| `opacity` | `number` | Opacity from 0 (invisible) to 1 (fully opaque). |
+| `visible` | `boolean` | Whether the widget is rendered and visible. |
+| `disabled` | `boolean` | Disables interaction and shows the non-interactive state. |
+| `onPress` | `(widget: Widget) => void` | Callback fired when the widget is pressed. Alias: `onClick`. |
+| `onClick` | `(widget: Widget) => void` | Callback fired when the widget is clicked. Alias: `onPress`. |
+| `id` | `string` | DOM `id` for the rendered element. |
+| `className` | `string` | CSS class names applied to the rendered element. |
+| `ref` | `(widget: Widget) => void` | Callback that receives the underlying DOM node. |
+| `disableTransform` | `boolean` | Disables the default press/scale transform animation. |
+
+## Examples
+
+### Everyday
+
+```javascript
+import { Dropdown } from "flet-box";
+
+const role = Dropdown({
+  label: "Role",
+  options: ["Admin", "Editor", "Viewer"],
+  value: "Editor",
+  onChange: (value) => console.log("role:", value),
+});
+```
+
+### Full
+
+```javascript
+import { Dropdown } from "flet-box";
+
+const country = Dropdown({
+  label: "Country",
+  variant: "outlined",
+  size: "medium",
+  options: [
+    { value: "us", label: "United States" },
+    { value: "de", label: "Germany" },
+    { value: "jp", label: "Japan" },
+  ],
+  value: "de",
+  clearable: true,
+  portal: true,
+  borderRadius: 10,
+  bgColor: "#ffffff",
+  textColor: "#0f172a",
+  onChange: (value, label) => {
+    console.log("selected:", value, label);
+  },
+});
+```
+
+## Tips
+
+- Pass objects with value/label when the value sent to onChange must differ from the text shown, such as an id versus a name.
+- Set clearable: true to give users an explicit way back to no selection.
+
+## Accessibility
+
+- Supply the label prop so the trigger has a visible field name, and ensure the menu can be opened without a mouse.
+
+## Behavior
+
+- The option menu is portaled to document.body by default and repositions on scroll/resize; set portal: false to keep it inline.
+- The returned element exposes value, open(), close() and update(), and removes its listeners on unmount.
+
+## Related widgets
+
+- [Radio](Radio.md)
+- [Checkbox](Checkbox.md)
+- [Input](Input.md)
+
+---
+
+## Continue reading
+
+- **Previous:** [Slider](Slider.md)
+- **Next:** [Rating](Rating.md)
+- **Index:** [Widget index](README.md) · [Start here](START_HERE.md)
+
+You are reading **Chapter 2 · Interaction basics** (7 of 8).

package/docs/widget/DroppBox.md

@@ -0,0 +1,152 @@
+# DroppBox
+
+A drop target for DraggBox items. It validates incoming payloads against acceptGroups and reports successful drops through onDrop.
+
+## When to use it
+
+Use it as a container that receives dragged items, such as a column on a kanban board.
+
+## Quick start
+
+```javascript
+import { DroppBox, Text } from "flet-box";
+
+const zone = DroppBox({
+  child: Text({ text: "Drop here" }),
+});
+```
+
+> The prop table is generated from `src/index.d.ts`; the examples use only documented props.
+
+## Props
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `child` | `Widget` | A single child widget. Alias: `children` for a list. |
+| `onDrop` | `(data: any, group: string, event: DragEvent) => void` | Fired when an item is dropped on the target. |
+| `onDragEnter` | `(event: DragEvent) => void` | Fired when a dragged item enters the target. |
+| `onDragLeave` | `(event: DragEvent) => void` | Fired when a dragged item leaves the target. |
+| `onDragOver` | `(event: DragEvent) => void` | Fired continuously while an item is dragged over the target. |
+| `acceptGroups` | `string[]` | Drag groups this target accepts. |
+| `disabled` | `boolean` | Disables interaction and shows the non-interactive state. |
+| `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
+| `borderRadius` | `number` | Rounds the corners of the widget. |
+| `borderWidth` | `number` | Width of the border. |
+| `borderStyle` | `string` | The `borderStyle` value for the widget. |
+| `borderColor` | `Color` | Color used for the border. |
+| `shadow` | `string` | Raw CSS `box-shadow` value, for a custom shadow. |
+| `padding` | `Padding` | Space inside the widget, between its content and its border. |
+| `activeBgColor` | `Color` | Background color for the active. |
+| `activeBorderColor` | `Color` | Border color for the active. |
+| `activeBorderWidth` | `number` | Border width for the active. |
+| `activeBorderStyle` | `string` | Border style for the active. |
+| `activeShadow` | `string` | The `activeShadow` value for the widget. |
+| `validBgColor` | `Color` | Background color for the valid. |
+| `validBorderColor` | `Color` | Border color for the valid. |
+| `invalidBgColor` | `Color` | Background color for the invalid. |
+| `invalidBorderColor` | `Color` | Border color for the invalid. |
+| `transitionDuration` | `string` | Duration for the transition, in milliseconds. |
+| `transitionTiming` | `string` | The `transitionTiming` value for the widget. |
+| `showFeedback` | `boolean` | Shows valid/invalid feedback during a drag. |
+
+### Common props
+
+Every widget also accepts these shared props — see [common props](COMMON_PROPS.md) for the full rules and aliases.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `width` | `Size` | Width of the widget. A number is pixels; a string uses any CSS unit. |
+| `height` | `Size` | Height of the widget. A number is pixels; a string uses any CSS unit. |
+| `size` | `Size` | Overall size preset or pixel value, depending on the widget. |
+| `padding` | `Padding` | Space inside the widget, between its content and its border. |
+| `margin` | `Margin` | Space outside the widget, between it and its neighbors. |
+| `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
+| `color` | `Color` | Foreground color, usually the text or icon color. |
+| `borderRadius` | `number \| string` | Rounds the corners of the widget. |
+| `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |
+| `shadow` | `string` | Raw CSS `box-shadow` value, for a custom shadow. |
+| `opacity` | `number` | Opacity from 0 (invisible) to 1 (fully opaque). |
+| `visible` | `boolean` | Whether the widget is rendered and visible. |
+| `disabled` | `boolean` | Disables interaction and shows the non-interactive state. |
+| `onPress` | `(widget: Widget) => void` | Callback fired when the widget is pressed. Alias: `onClick`. |
+| `onClick` | `(widget: Widget) => void` | Callback fired when the widget is clicked. Alias: `onPress`. |
+| `id` | `string` | DOM `id` for the rendered element. |
+| `className` | `string` | CSS class names applied to the rendered element. |
+| `ref` | `(widget: Widget) => void` | Callback that receives the underlying DOM node. |
+| `disableTransform` | `boolean` | Disables the default press/scale transform animation. |
+
+## Examples
+
+### Everyday
+
+```javascript
+import { DroppBox, Text } from "flet-box";
+
+const zone = DroppBox({
+  child: Text({ text: "Drop a task here" }),
+  acceptGroups: ["tasks"],
+  onDrop: (data, group) => console.log(data, group),
+});
+```
+
+### Full
+
+```javascript
+import { Container, DroppBox, Text } from "flet-box";
+
+const zone = DroppBox({
+  child: Container({
+    padding: 24,
+    child: Text({ text: "Drop tasks here" }),
+  }),
+  acceptGroups: ["kanban"],
+  showFeedback: true,
+  bgColor: "#f8fafc",
+  borderWidth: 2,
+  borderStyle: "dashed",
+  borderColor: "#cbd5e1",
+  borderRadius: 12,
+  padding: 16,
+  activeBgColor: "#eff6ff",
+  activeBorderColor: "#2563eb",
+  validBgColor: "#f0fdf4",
+  validBorderColor: "#16a34a",
+  invalidBgColor: "#fef2f2",
+  invalidBorderColor: "#dc2626",
+  transitionDuration: "150ms",
+  onDrop: (data, group, event) => console.log(data, group),
+  onDragEnter: () => console.log("enter"),
+});
+```
+
+## Tips
+
+- List the drag group values you allow in acceptGroups; unlisted groups are rejected.
+- Style activeBgColor and activeBorderColor so users see the target highlight during a drag.
+- Use validBgColor and invalidBgColor with showFeedback to signal whether a drop is allowed.
+
+## Accessibility
+
+- Pair drop zones with an alternative control, such as a move menu, for keyboard and touch users.
+- Make the target's purpose clear with visible text, not just a highlighted border.
+
+## Behavior
+
+- onDrop fires with the data, group and event when an accepted item is released.
+- onDragEnter, onDragOver and onDragLeave fire as the pointer passes over the target.
+
+## Related widgets
+
+- [DraggBox](DraggBox.md)
+- [Container](Container.md)
+- [Card](Card.md)
+
+---
+
+## Continue reading
+
+- **Previous:** [DraggBox](DraggBox.md)
+- **Next:** [Scaffold](Scaffold.md) — Chapter 8 · App navigation
+- **Index:** [Widget index](README.md) · [Start here](START_HERE.md)
+
+You are reading **Chapter 7 · Media and drag & drop** (4 of 4).