flet-box 1.0.4 → 1.0.5

package/docs/widget/Tooltip.md

@@ -0,0 +1,145 @@
+# Tooltip
+
+Wraps a child widget and shows a labeled overlay bubble on hover or focus. The bubble is rendered as a portal on document.body so it is never clipped.
+
+## When to use it
+
+Use it to explain icons, buttons, or dense fields that cannot fit a visible label.
+
+## Quick start
+
+```javascript
+import { Button, Tooltip, clipboard } from "flet-box";
+
+const tip = Tooltip({
+  text: "Copy to clipboard",
+  child: Button({ text: "Copy" }),
+});
+```
+
+> The prop table is generated from `src/index.d.ts`; the examples use only documented props.
+
+## Props
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `text` | `string` | Visible text content. |
+| `child` | `Widget` | A single child widget. Alias: `children` for a list. |
+| `position` | `'top' \| 'bottom' \| 'left' \| 'right'` | CSS `position` value, or `stack` for centered stacking. |
+| `delay` | `number` | Delay before the animation starts, in milliseconds. |
+| `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
+| `textColor` | `Color` | Color of the button label. |
+| `fontSize` | `number` | Size of the font. |
+| `padding` | `Padding` | Space inside the widget, between its content and its border. |
+| `borderRadius` | `number` | Rounds the corners of the widget. |
+| `offset` | `number` | The `offset` value for the widget. |
+| `showArrow` | `boolean` | Controls whether the arrow is shown. |
+| `disabled` | `boolean` | Disables interaction and shows the non-interactive state. |
+| `maxWidth` | `number` | Maximum width the widget may grow to. |
+| `textAlign` | `'left' \| 'center' \| 'right'` | The `textAlign` value for the widget. |
+| `zIndex` | `number` | Index used for the z. |
+| `animationDuration` | `number` | Duration for the animation, in milliseconds. |
+| `arrowSize` | `number` | Size of the arrow. |
+| `borderColor` | `Color` | Color used for the border. |
+| `borderWidth` | `number` | Width of the border. |
+| `shadow` | `string` | Raw CSS `box-shadow` value, for a custom shadow. |
+
+### 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 { Icon, Tooltip } from "flet-box";
+
+const tip = Tooltip({
+  text: "Adds the item to your cart",
+  position: "bottom",
+  delay: 150,
+  child: Icon({ name: "shopping_cart" }),
+});
+```
+
+### Full
+
+```javascript
+import { Button, Tooltip, rgba } from "flet-box";
+
+const tip = Tooltip({
+  text: "Only visible to workspace admins",
+  child: Button({ text: "Share", variant: "outlined" }),
+  position: "right",
+  delay: 300,
+  offset: 12,
+  maxWidth: 240,
+  bgColor: "#111827",
+  textColor: "#f9fafb",
+  showArrow: true,
+  textAlign: "left",
+  borderRadius: 8,
+  shadow: "0 4px 12px rgba(0,0,0,0.25)",
+  animationDuration: 180,
+});
+```
+
+## Tips
+
+- Attach it to any widget via child; the tooltip is a separate portal, so overflow
+- hidden ancestors do not cut it off.
+- delay controls how long the pointer must rest before the tooltip appears; lower it
+- for dense toolbars, raise it for error-prone hints.
+- The bubble is clamped to the viewport edges, so top/left placements can sit slightly
+- inside the window bounds.
+
+## Accessibility
+
+- The wrapped child keeps its focus handlers, so keyboard users tabbing onto it get
+- the same tooltip as mouse hover.
+
+## Behavior
+
+- The tooltip hides itself on window scroll or resize and removes its body portal plus
+- listeners on unmount.
+- The wrapped child gains showTooltip, hideTooltip, updateContent, and updatePosition
+- helpers for imperative control.
+
+## Related widgets
+
+- [Button](Button.md)
+- [Icon](Icon.md)
+- [Text](Text.md)
+
+---
+
+## Continue reading
+
+- **Previous:** [SnackBar](SnackBar.md)
+- **Next:** [ProgressBar](ProgressBar.md)
+- **Index:** [Widget index](README.md) · [Start here](START_HERE.md)
+
+You are reading **Chapter 4 · Feedback and overlays** (5 of 10).

package/docs/widget/TreeView.md

@@ -0,0 +1,176 @@
+# TreeView
+
+TreeView renders a collapsible hierarchy from nodes, each with an id, label, optional icon, badge and children. It supports expand/collapse, selection and nested navigation.
+
+## When to use it
+
+Use it for file explorers, category menus or any nested set of items the user drills into.
+
+## Quick start
+
+```javascript
+import { TreeView } from "flet-box";
+
+const tree = TreeView({
+  nodes: [
+    { id: "src", label: "src" },
+  ],
+});
+```
+
+> The prop table is generated from `src/index.d.ts`; the examples use only documented props.
+
+## Props
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `nodes` | `Array<{` | Tree nodes, each with `id`, `label`, and optional `children`. |
+| `id` | `string` | DOM `id` for the rendered element. |
+| `label` | `string` | Label or caption shown near the control. |
+| `icon` | `string` | Name of the icon to render. |
+| `iconColor` | `Color` | Color of the field icons. |
+| `children` | `any[]` | An array of child widgets. Alias: `child` for a single child. |
+| `badge` | `string \| number` | The `badge` value for the widget. |
+| `onSelect` | `(node: any) => void` | Fired when the widget or an option is selected. |
+| `onToggle` | `(nodeId: string, expanded: boolean) => void` | Fired with the new toggled state. |
+| `expandedNodes` | `string[]` | Ids of nodes that start expanded. |
+| `indent` | `number` | Indentation depth used when printing nested structures. |
+| `showIcons` | `boolean` | Controls whether the icons is shown. |
+| `folderIcon` | `string` | Icon for the folder. |
+| `folderOpenIcon` | `string` | Icon for the folder open. |
+| `fileIcon` | `string` | Icon for the file. |
+| `expandIcon` | `string` | Icon for the expand. |
+| `collapseIcon` | `string` | Icon for the collapse. |
+| `defaultExpanded` | `boolean` | Expands top-level nodes by default. |
+| `selectable` | `boolean` | Lets the user select a tree node. |
+| `selectedNodeId` | `string \| null` | Id of the currently selected node. |
+| `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
+| `hoverBgColor` | `Color` | Background color for the hover. |
+| `selectedBgColor` | `Color` | Background color for the selected. |
+| `textColor` | `Color` | Color of the button label. |
+| `selectedTextColor` | `Color` | Color used for the selected text. |
+| `iconColor` | `Color` | Color of the field icons. |
+| `folderIconColor` | `Color` | Color used for the folder icon. |
+| `borderColor` | `Color` | Color used for the border. |
+| `nodePadding` | `Padding` | Padding for the node. |
+| `nodeGap` | `number` | Space for the node. |
+| `childrenGap` | `number` | Space for the children. |
+| `borderRadius` | `number` | Rounds the corners of the widget. |
+| `fontSize` | `number` | Size of the font. |
+| `iconSize` | `number` | Size of the field icons. |
+| `transitionDuration` | `string` | Duration for the transition, in milliseconds. |
+
+### 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 { TreeView } from "flet-box";
+
+const tree = TreeView({
+  nodes: [
+    {
+      id: "src",
+      label: "src",
+      children: [
+        { id: "app", label: "app.js" },
+        { id: "router", label: "Router.js" },
+      ],
+    },
+  ],
+  showIcons: true,
+  onSelect: (node) => console.log(node.id),
+});
+```
+
+### Full
+
+```javascript
+import { TreeView } from "flet-box";
+
+const tree = TreeView({
+  nodes: [
+    {
+      id: "src",
+      label: "src",
+      icon: "folder",
+      children: [
+        { id: "app", label: "app.js", icon: "description" },
+        { id: "router", label: "Router.js", badge: 2 },
+      ],
+    },
+  ],
+  expandedNodes: ["src"],
+  defaultExpanded: true,
+  selectable: true,
+  showIcons: true,
+  selectedNodeId: "app",
+  indent: 20,
+  nodeGap: 4,
+  childrenGap: 4,
+  fontSize: 14,
+  transitionDuration: "200ms",
+  hoverBgColor: "#f1f5f9",
+  selectedBgColor: "#dbeafe",
+  onToggle: (nodeId, expanded) => console.log(nodeId, expanded),
+  onSelect: (node) => console.log(node.id),
+});
+```
+
+## Tips
+
+- Give every node a stable unique id; expandedNodes and selectedNodeId reference those ids.
+- Set selectable to false for navigation trees where tapping should only toggle groups.
+- Use defaultExpanded to open first-level groups on first render.
+
+## Accessibility
+
+- Expose meaningful label text and do not rely only on icons to describe a node.
+- Keep onSelect behavior predictable so keyboard users understand what activation does.
+
+## Behavior
+
+- Nodes toggle locally and report expansion through onToggle with the nodeId and expanded flag.
+- Selection is reported through onSelect as the node object and can be controlled with selectedNodeId.
+
+## Related widgets
+
+- [ListView](ListView.md)
+- [ListTile](ListTile.md)
+- [Accordion](Accordion.md)
+
+---
+
+## Continue reading
+
+- **Previous:** [Accordion](Accordion.md)
+- **Next:** [Carousel](Carousel.md)
+- **Index:** [Widget index](README.md) · [Start here](START_HERE.md)
+
+You are reading **Chapter 5 · Navigation and flows** (3 of 5).

package/docs/widget/Video.md

@@ -0,0 +1,127 @@
+# Video
+
+Renders a native <video> element with proper media attributes and a convenient playback API. Helpers for play, pause, stop, restart, and volume.
+
+## When to use it
+
+Use it to embed a clip, trailer, ambient background video, or lecture recording.
+
+## Quick start
+
+```javascript
+import { Video } from "flet-box";
+
+const clip = Video({
+  src: "/media/intro.mp4",
+});
+```
+
+> The prop table is generated from `src/index.d.ts`; the examples use only documented props.
+
+## Props
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `src` | `string` | Resource URL for the image, audio, or video. |
+| `width` | `number \| string` | Width of the widget. A number is pixels; a string uses any CSS unit. |
+| `height` | `number \| string` | Height of the widget. A number is pixels; a string uses any CSS unit. |
+| `autoplay` | `boolean` | Starts playback automatically. |
+| `controls` | `boolean` | Shows the native media playback controls. |
+| `loop` | `boolean` | Restarts playback when it reaches the end. |
+| `muted` | `boolean` | Starts playback with the audio muted. |
+| `poster` | `string` | Image shown before a video starts playing. |
+| `ref` | `(video: HTMLVideoElement) => void` | Callback that receives the underlying DOM node. |
+
+### 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 { Video } from "flet-box";
+
+const clip = Video({
+  src: "/media/intro.mp4",
+  controls: true,
+  width: "100%",
+  height: 360,
+  poster: "/media/intro-poster.jpg",
+});
+```
+
+### Full
+
+```javascript
+import { Video } from "flet-box";
+
+const clip = Video({
+  src: "/media/demo.mp4",
+  width: "100%",
+  height: 480,
+  controls: true,
+  autoplay: false,
+  loop: true,
+  muted: true,
+  poster: "/media/demo-poster.jpg",
+  ref: (video) => video.playVideo(),
+});
+```
+
+## Tips
+
+- controls, loop, muted, and autoplay are set as element properties, not CSS, so they
+- work even though they look like styling props.
+- Browsers block autoplay with sound; pair autoplay: true with muted: true for a
+- reliable ambient loop.
+- The ref callback receives the element extended with playVideo, pauseVideo, stop,
+- restart, volumeUp, and muteVideo helpers.
+
+## Accessibility
+
+- Keep controls: true so keyboard and screen-reader users can operate playback.
+
+## Behavior
+
+- playVideo swallows the browser's autoplay rejection instead of throwing, so it is
+- safe to call from a click handler.
+
+## Related widgets
+
+- [Audio](Audio.md)
+- [Image](Image.md)
+- [Card](Card.md)
+
+---
+
+## Continue reading
+
+- **Previous:** [Audio](Audio.md)
+- **Next:** [DraggBox](DraggBox.md)
+- **Index:** [Widget index](README.md) · [Start here](START_HERE.md)
+
+You are reading **Chapter 7 · Media and drag & drop** (2 of 4).

package/docs/widget/_template.md

@@ -0,0 +1,61 @@
+# WidgetName
+
+## Overview
+
+Explain what the widget is for in one or two sentences.
+
+## When to use it
+
+Describe the situation in which you reach for this widget.
+
+## Quick start
+
+```javascript
+import { WidgetName } from "flet-box";
+
+const example = WidgetName({
+  // the smallest useful call
+});
+```
+
+## Props
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `propName` | `Type` | What the prop does. |
+
+## Examples
+
+### Everyday
+
+Show the most common combination of props.
+
+### Full
+
+Show advanced layout, styling and events.
+
+## Tips
+
+- Practical, widget-specific advice.
+
+## Accessibility
+
+- Keyboard and screen-reader considerations.
+
+## Behavior
+
+- Layout, interaction and re-render notes.
+
+## Related widgets
+
+- [Container](Container.md)
+
+---
+
+## Continue reading
+
+- **Previous:** ...
+- **Next:** ...
+- **Index:** [Widget index](README.md) · [Start here](START_HERE.md)
+
+You are reading **Chapter N · Title** (i of m).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flet-box",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "description": "Declarative, zero-dependency UI framework in vanilla JS — ship web, PWA, Android and iOS from one codebase",
   "type": "module",
   "main": "src/index.js",
@@ -19,7 +19,7 @@
     "dev": "node bin/cli.js run --hot",
     "build": "node bin/cli.js createBundle",
     "release": "node bin/cli.js release",
-    "test": "node scripts/check-widgets.mjs && node scripts/check-api-surface.mjs",
+    "test": "node scripts/check-widgets.mjs && node scripts/check-prop-registry.mjs && node scripts/check-docs-props.mjs && node scripts/check-api-surface.mjs && node scripts/check-router-base.mjs && python3 tools/snippets-creator-flet-box/build_snippets.py --check && node scripts/check-snippets.mjs",
     "test:browser": "node scripts/run-browser-tests.mjs"
   },
   "keywords": [
@@ -52,6 +52,7 @@
   "files": [
     "bin/",
     "src/",
+    "docs/",
     "README.md",
     "LICENSE"
   ],