flet-box 1.0.4 → 1.0.6

package/docs/widget/Chip.md

@@ -0,0 +1,126 @@
+# Chip
+
+A compact, pill-shaped label for tags, filters, and selections. It can carry a leading icon and a delete affordance.
+
+## When to use it
+
+Use it to represent selected filters, categories, or removable tokens.
+
+## Quick start
+
+```javascript
+import { Chip } from "flet-box";
+
+const tag = Chip({
+  label: "Design",
+});
+```
+
+> The prop table is generated from `src/index.d.ts`; the examples use only documented props.
+
+## Props
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `label` | `string` | Label or caption shown near the control. |
+| `icon` | `string` | Name of the icon to render. |
+| `onPress` | `() => void` | Callback fired when the widget is pressed. Alias: `onClick`. |
+| `onDelete` | `() => void` | Event handler for the `onDelete` event. |
+| `variant` | `'filled' \| 'outlined'` | Visual variation or style preset. |
+| `color` | `Color` | Foreground color, usually the text or icon color. |
+| `textColor` | `Color` | Color of the button label. |
+| `borderColor` | `Color` | Color used for the border. |
+| `size` | `'small' \| 'medium' \| 'large'` | Overall size preset or pixel value, depending on the widget. |
+| `borderRadius` | `number \| string` | Rounds the corners of the widget. |
+| `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |
+| `gap` | `number` | Space between children along the layout axis. |
+
+### 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 { Chip, filter } from "flet-box";
+
+const tag = Chip({
+  label: "Design",
+  icon: "palette",
+  onPress: () => console.log("filter by design"),
+});
+```
+
+### Full
+
+```javascript
+import { Chip, filter } from "flet-box";
+
+const tag = Chip({
+  label: "Design",
+  icon: "palette",
+  variant: "outlined",
+  size: "small",
+  color: "#eff6ff",
+  textColor: "#1d4ed8",
+  borderColor: "#bfdbfe",
+  borderRadius: 999,
+  gap: 6,
+  onPress: () => console.log("filter by design"),
+  onDelete: () => console.log("removed"),
+});
+```
+
+## Tips
+
+- Use variant: "outlined" for unselected filters and a filled color once active.
+- Add onDelete only when the chip represents a removable value.
+
+## Accessibility
+
+- The label text is the accessible name, so keep it a single clear word or short phrase.
+
+## Behavior
+
+- onPress fires from the chip body; onDelete fires from the trailing close control.
+- A chip with onPress but no onDelete behaves like a small toggle button.
+
+## Related widgets
+
+- [Badge](Badge.md)
+- [Avatar](Avatar.md)
+- [Button](Button.md)
+
+---
+
+## Continue reading
+
+- **Previous:** [Badge](Badge.md)
+- **Next:** [AlertDialog](AlertDialog.md)
+- **Index:** [Widget index](README.md) · [Start here](START_HERE.md)
+
+You are reading **Chapter 3 · Layout, cards and lists** (8 of 8).

package/docs/widget/CircularBar.md

@@ -0,0 +1,168 @@
+# CircularBar
+
+A circular or radial progress indicator drawn on canvas. It can show a percentage or raw value, an optional label, gradients, glow, and markers.
+
+## When to use it
+
+Use it for scan-style progress, scores, budgets, or any gauge that benefits from a ring layout instead of a horizontal bar.
+
+## Quick start
+
+```javascript
+import { CircularBar } from "flet-box";
+
+const progress = CircularBar({
+  value: 72,
+});
+```
+
+> The prop table is generated from `src/index.d.ts`; the examples use only documented props.
+
+## Props
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `value` | `number` | Current value controlled by the widget. |
+| `max` | `number` | Maximum value used to compute the ratio. |
+| `size` | `number` | Overall size preset or pixel value, depending on the widget. |
+| `strokeWidth` | `number` | Thickness of the circular stroke. |
+| `color` | `Color` | Foreground color, usually the text or icon color. |
+| `backgroundColor` | `Color` | Background color. Alias of `bgColor`. |
+| `showValue` | `boolean` | Shows the numeric value next to the indicator. |
+| `valueColor` | `Color` | Color used for the value. |
+| `valueSize` | `number` | Size of the value. |
+| `label` | `string` | Label or caption shown near the control. |
+| `labelColor` | `Color` | Color used for the label. |
+| `labelSize` | `number` | Size of the label. |
+| `lineCap` | `'butt' \| 'round' \| 'square'` | Shape of the ends of the progress stroke. |
+| `animate` | `boolean` | The `animate` value for the widget. |
+| `animationDuration` | `number` | Duration for the animation, in milliseconds. |
+| `onComplete` | `() => void` | Event handler for the `onComplete` event. |
+| `ref` | `(canvas: HTMLCanvasElement) => void` | Callback that receives the underlying DOM node. |
+| `valueFormat` | `'percent' \| 'value' \| 'custom'` | Formats the displayed value. |
+| `valueSuffix` | `string` | Text appended after the displayed value. |
+| `valuePrefix` | `string` | Text prepended before the displayed value. |
+| `valueDecimals` | `number` | Number of decimals in the displayed value. |
+| `customValueFormatter` | `(value: number, max: number) => string` | Function that returns the formatted value string. |
+| `gradient` | `string \| string[]` | CSS gradient used as the fill. |
+| `gradientAngle` | `number` | The `gradientAngle` value for the widget. |
+| `shadowBlur` | `number` | The `shadowBlur` value for the widget. |
+| `shadowColor` | `string` | Color used for the shadow. |
+| `glow` | `boolean` | Adds a glow around the widget. |
+| `glowColor` | `string` | Color of the glow. |
+| `markers` | `Array<{ value: number; color?: Color; size?: number; label?: string }>` | Marker ticks drawn along the progress arc. |
+| `innerStrokeWidth` | `number` | Width of the inner stroke. |
+| `innerColor` | `Color` | Color used for the inner. |
+| `onClick` | `(data: { value: number; max: number; percent: number }) => void` | Callback fired when the widget is clicked. Alias: `onPress`. |
+| `onHover` | `(hovering: boolean, data: { value: number; max: number }) => void` | Event handler for the `onHover` event. |
+| `subtitle` | `string` | The `subtitle` value for the widget. |
+| `subtitleColor` | `Color` | Color used for the subtitle. |
+| `subtitleSize` | `number` | Size of the subtitle. |
+| `tooltip` | `string` | The `tooltip` value for the widget. |
+
+### 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 { CircularBar } from "flet-box";
+
+const progress = CircularBar({
+  value: 72,
+  max: 100,
+  size: 160,
+  color: "#2563eb",
+  backgroundColor: "#e5e7eb",
+  showValue: true,
+});
+```
+
+### Full
+
+```javascript
+import { CircularBar } from "flet-box";
+
+const progress = CircularBar({
+  value: 820,
+  max: 1000,
+  size: 200,
+  strokeWidth: 16,
+  color: "#10b981",
+  backgroundColor: "#e5e7eb",
+  valueFormat: "value",
+  valuePrefix: "$",
+  valueDecimals: 0,
+  label: "Revenue",
+  subtitle: "this month",
+  lineCap: "round",
+  animate: true,
+  animationDuration: 900,
+  gradient: ["#34d399", "#059669"],
+  onComplete: () => console.log("done"),
+  onClick: (data) => console.log(data.percent),
+});
+```
+
+## Tips
+
+- Leave size unset to fill the parent width, or set size for a fixed square canvas.
+- valueFormat accepts "percent", "value", or "custom"; customValueFormatter
+- overrides how the number is rendered entirely.
+- When valueFormat is "value", use valuePrefix and valueSuffix to render units like
+- "$" or "%".
+
+## Accessibility
+
+- Canvas contents are invisible to assistive technology, so add a label or subtitle
+- next to the bar to give the number context.
+
+## Behavior
+
+- With animate: true the sweep animates from zero and onComplete fires once it reaches
+- the target value.
+- Clicking the bar passes { value, max, percent } to onClick; hovering toggles the
+- onHover boolean.
+- When size is unset the canvas re-measures its container via ResizeObserver and
+- releases the observer on unmount.
+
+## Related widgets
+
+- [CircularChart](CircularChart.md)
+- [ProgressBar](ProgressBar.md)
+- [Rating](Rating.md)
+
+---
+
+## Continue reading
+
+- **Previous:** [ProgressBar](ProgressBar.md)
+- **Next:** [Skeleton](Skeleton.md)
+- **Index:** [Widget index](README.md) · [Start here](START_HERE.md)
+
+You are reading **Chapter 4 · Feedback and overlays** (7 of 10).

package/docs/widget/CircularChart.md

@@ -0,0 +1,164 @@
+# CircularChart
+
+A pie or donut chart drawn on canvas with per-slice value, label, and color. It supports rounded slices, semi-circles, center content, and entry animation.
+
+## When to use it
+
+Use it to show part-to-whole breakdowns such as traffic sources, spending, or task status distribution.
+
+## Quick start
+
+```javascript
+import { CircularChart } from "flet-box";
+
+const chart = CircularChart({
+  data: [
+    { value: 60, label: "Direct", color: "#2563eb" },
+    { value: 40, label: "Referral", color: "#10b981" },
+  ],
+});
+```
+
+> The prop table is generated from `src/index.d.ts`; the examples use only documented props.
+
+## Props
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `data` | `CircularChartSlice[]` | Array of values or `{ label, value }` slices. |
+| `size` | `number` | Overall size preset or pixel value, depending on the widget. |
+| `strokeWidth` | `number` | Thickness of the circular stroke. |
+| `innerRadius` | `number` | Radius of the empty center of a donut. |
+| `rounded` | `boolean` | The `rounded` value for the widget. |
+| `cornerRadius` | `number` | Corner radius for the corner. |
+| `startAngle` | `number` | Starting angle of the arc, in degrees. |
+| `endAngle` | `number` | Ending angle of the arc, in degrees. |
+| `animate` | `boolean` | The `animate` value for the widget. |
+| `animationDuration` | `number` | Duration for the animation, in milliseconds. |
+| `onComplete` | `() => void` | Event handler for the `onComplete` event. |
+| `centerContent` | `string \| Widget \| null` | Widget rendered in the center of the circle. |
+| `showLabels` | `boolean` | Shows chart labels. |
+| `labelSize` | `number` | Size of the label. |
+| `labelColor` | `Color` | Color used for the label. |
+| `onClick` | `(slice: CircularChartSlice, index: number) => void` | Callback fired when the widget is clicked. Alias: `onPress`. |
+| `onHover` | `(slice: CircularChartSlice \| null, index: number) => void` | Event handler for the `onHover` event. |
+| `defaultColors` | `Color[]` | The `defaultColors` value for the widget. |
+| `ref` | `(canvas: HTMLCanvasElement) => void` | Callback that receives the underlying DOM node. |
+| `shadowBlur` | `number` | The `shadowBlur` value for the widget. |
+| `shadowColor` | `string` | Color used for the shadow. |
+| `glow` | `boolean` | Adds a glow around the widget. |
+| `glowColor` | `string` | Color of the glow. |
+| `semiCircle` | `'top' \| 'bottom' \| 'left' \| 'right' \| null` | The `semiCircle` value for the widget. |
+| `borderRadius` | `number` | Rounds the corners of the widget. |
+| `borderColor` | `Color` | Color used for the border. |
+| `borderWidth` | `number` | Width of the border. |
+| `sliceBorderWidth` | `number` | Border width for the slice. |
+| `sliceBorderColor` | `Color` | Border color for the slice. |
+
+### 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 { CircularChart } from "flet-box";
+
+const chart = CircularChart({
+  data: [
+    { value: 60, label: "Direct", color: "#2563eb" },
+    { value: 25, label: "Search", color: "#f59e0b" },
+    { value: 15, label: "Social", color: "#ef4444" },
+  ],
+  size: 200,
+  strokeWidth: 24,
+  showLabels: true,
+});
+```
+
+### Full
+
+```javascript
+import { CircularChart } from "flet-box";
+
+const chart = CircularChart({
+  data: [
+    { value: 42, label: "Desktop", color: "#2563eb" },
+    { value: 33, label: "Mobile", color: "#10b981" },
+    { value: 25, label: "Tablet", color: "#f59e0b" },
+  ],
+  size: 240,
+  strokeWidth: 28,
+  innerRadius: 70,
+  cornerRadius: 6,
+  startAngle: -Math.PI / 2,
+  animate: true,
+  animationDuration: 800,
+  showLabels: true,
+  labelSize: 13,
+  centerContent: "Traffic",
+  sliceBorderWidth: 2,
+  sliceBorderColor: "#ffffff",
+  onHover: (slice, index) => console.log(slice?.label, index),
+  onClick: (slice, index) => console.log(slice.label, index),
+  onComplete: () => console.log("drawn"),
+});
+```
+
+## Tips
+
+- Each slice is { value, label, color }; omit color to take colors from defaultColors
+- in order.
+- Set innerRadius for a donut, or widen strokeWidth relative to size to make a ring.
+- semiCircle: "top" renders a half gauge and adjusts the canvas aspect to match.
+
+## Accessibility
+
+- Canvas slices are not read by screen readers; mirror the same data in text or a
+- table legend beside the chart.
+
+## Behavior
+
+- centerContent accepts a string or a widget rendered in the donut hole.
+- onHover receives (slice | null, index) as the pointer moves between slices, and
+- onComplete fires when the entry sweep finishes.
+
+## Related widgets
+
+- [CircularBar](CircularBar.md)
+- [Chart](Chart.md)
+- [Card](Card.md)
+
+---
+
+## Continue reading
+
+- **Previous:** [Chart](Chart.md)
+- **Next:** [Markdown](Markdown.md)
+- **Index:** [Widget index](README.md) · [Start here](START_HERE.md)
+
+You are reading **Chapter 6 · Data, rich content & effects** (3 of 13).

package/docs/widget/CodeViewer.md

@@ -0,0 +1,130 @@
+# CodeViewer
+
+CodeViewer shows a read-only code block with an optional header, line numbers and scrolling for long files. It renders the code prop verbatim in a styled monospace container.
+
+## When to use it
+
+Use it to display snippets, config or logs in docs and developer tools without building your own pre/code styling.
+
+## Quick start
+
+```javascript
+import { CodeViewer } from "flet-box";
+
+const snippet = CodeViewer({
+  code: "const total = price * qty;",
+});
+```
+
+> The prop table is generated from `src/index.d.ts`; the examples use only documented props.
+
+## Props
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `code` | `string` | Source code to display. |
+| `title` | `string` | Title text shown in the header. |
+| `maxHeight` | `number` | Maximum height the widget may grow to. |
+| `fontSize` | `number` | Size of the font. |
+| `backgroundColor` | `Color` | Background color. Alias of `bgColor`. |
+| `padding` | `Padding` | Space inside the widget, between its content and its border. |
+| `borderRadius` | `number` | Rounds the corners of the widget. |
+| `showHeader` | `boolean` | Shows the code viewer header. |
+| `showLineNumbers` | `boolean` | Shows line numbers in the gutter. |
+| `startingLineNumber` | `number` | The `startingLineNumber` value for the widget. |
+| `lineNumberWidth` | `number` | Width of the line number. |
+| `lineNumberColor` | `Color` | Color used for the line number. |
+
+### 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 { CodeViewer } from "flet-box";
+
+const viewer = CodeViewer({
+  code: "function add(a, b) {\n  return a + b;\n}",
+  title: "math.js",
+  showLineNumbers: true,
+  maxHeight: 320,
+});
+```
+
+### Full
+
+```javascript
+import { CodeViewer } from "flet-box";
+
+const viewer = CodeViewer({
+  code: "export function login(user) {\n  return api.post('/auth', user);\n}",
+  title: "auth.js",
+  showHeader: true,
+  showLineNumbers: true,
+  startingLineNumber: 10,
+  lineNumberWidth: 40,
+  fontSize: 13,
+  maxHeight: 400,
+  borderRadius: 8,
+  backgroundColor: "#0f172a",
+  lineNumberColor: "#64748b",
+  padding: 16,
+});
+```
+
+## Tips
+
+- Pass the full source in code; use showLineNumbers and startingLineNumber to match an excerpt's original numbers.
+- Cap tall blocks with maxHeight so the viewer scrolls instead of pushing the page layout.
+- Set title to label the file or language shown in the header.
+
+## Accessibility
+
+- Keep the code text selectable and readable; do not rely on color alone to convey meaning.
+- A descriptive title helps screen-reader users identify the snippet.
+
+## Behavior
+
+- The code is inserted as text content, so HTML in code is displayed rather than executed.
+- Line numbers are derived from code and update when the reactive code prop changes.
+
+## Related widgets
+
+- [Markdown](Markdown.md)
+- [Text](Text.md)
+- [Card](Card.md)
+
+---
+
+## Continue reading
+
+- **Previous:** [Markdown](Markdown.md)
+- **Next:** [QRCode](QRCode.md)
+- **Index:** [Widget index](README.md) · [Start here](START_HERE.md)
+
+You are reading **Chapter 6 · Data, rich content & effects** (5 of 13).